kira-wallet 0.2.1 → 0.2.3

package/README.md

@@ -15,7 +15,7 @@ web app to manage wallets, inspect token markets and follow research. Your
 existing AI agent can use the same records and actions through the Kira CLI or
 optional MCP connection, then open the web app beside your conversation.
 
-**This branch prepares 0.2.1.** Kira now supplies wallet tools and a full-window
+**Kira 0.2.2 is published on npm; this branch prepares 0.2.3.** Kira supplies wallet tools and a full-window
 management app. Your agent host manages its own conversations, models, files and
 approvals. Kira does not launch a model CLI or require a model login.
 
@@ -104,7 +104,9 @@ saved holdings; it does not discover additional tokens. Price refresh preserves
 recorded balances and does not recover missing holdings.
 
 DEX price references require at least $1,000 of reported pool liquidity and
-exclude extremely one-sided pools. A displayed value is an estimate, not a
+exclude extremely one-sided pools. Research and price refresh both fall back to
+Alchemy index prices when no DEX price or explicit liquidity rejection exists.
+An index price is a reference, not proof of a liquid market. A displayed value is an estimate, not a
 promise of sale proceeds. Observation timestamps remain attached to the facts.
 
 ## Upgrading from 0.1.20

package/cashout.py

@@ -3,6 +3,7 @@ from decimal import Decimal, InvalidOperation, localcontext
 import json
 from pathlib import Path
 import re
+from market_records import checked_price
 
 CRITERIA = {'version': 2, 'minimum_quoted_usd': '1', 'mintclub_redemption_included': True,
             'gas_included': False, 'execution_verified': False,
@@ -36,6 +37,7 @@ def output_price(chain_id, address, market):
     rows = [p for p in market.get('tokens', []) if p.get('chain_id') == chain_id
             and isinstance(p.get('address'), str) and p['address'].lower() == address.lower()]
     for row in rows:
+        row = checked_price(row)
         price = decimal(row.get('usd'))
         if (price is not None and price > 0 and row.get('quality') == 'estimated'
                 and row.get('basis') in ('DEX market', 'Market index')

package/curve_pricing.py

@@ -3,11 +3,41 @@ from concurrent.futures import ThreadPoolExecutor
 import json
 import math
 from pathlib import Path
-import subprocess
 import sys
 import research as h
 
 
+def index_prices(identities, folder, deadline=None):
+    """Read bounded Alchemy batches by exact chain/contract, retaining source time."""
+    from wallet import ALCHEMY, atomic, fetch
+    sys.path.insert(0,str(h.ASSETS/'viewer'))
+    from model import dex_price
+    import hashlib
+    import re
+    wanted=sorted({(cid,address.lower()) for cid,address in identities
+                   if cid in ALCHEMY and isinstance(address,str) and re.fullmatch(r'0x[0-9a-fA-F]{40}',address)})
+    key=h.secrets().get('ALCHEMY_CUSTOM_APY_KEY') if wanted else None
+    prices={}
+    for start in range(0,len(wanted) if key else 0,25):
+        batch=wanted[start:start+25]
+        requests=[{'network':ALCHEMY[cid],'address':address} for cid,address in batch]
+        file=Path(folder)/('reserve-price-cache-'+hashlib.sha256(json.dumps(requests,sort_keys=True).encode()).hexdigest()+'.json')
+        record=json.loads(file.read_text()) if file.exists() else None
+        if record is None:
+            response=fetch('https://api.g.alchemy.com/prices/v1/'+key+'/tokens/by-address',{'addresses':requests},deadline=deadline)
+            record={'observed_at':h.now(),'source':'Alchemy token prices by address','request':requests,'response':response}
+            if isinstance(response,dict) and isinstance(response.get('data'),list):atomic(file,record)
+        response=record.get('response')
+        expected={(ALCHEMY[cid],address):(cid,address) for cid,address in batch}
+        for row in response.get('data',[]) if isinstance(response,dict) and isinstance(response.get('data'),list) else []:
+            if not isinstance(row,dict) or row.get('error') or not isinstance(row.get('network'),str) or not isinstance(row.get('address'),str):continue
+            identity=expected.get((row['network'],row['address'].lower()))
+            if identity is None or not isinstance(row.get('prices'),list):continue
+            price=dex_price({'token_address':identity[1],'indexer_price_references':[p for p in row['prices'] if isinstance(p,dict)]},None)
+            if price:prices[identity]={'chain_id':identity[0],'address':identity[1],**price}
+    return {'tokens':list(prices.values()),'status':'partial' if len(prices)<len(wanted) else 'checked'}
+
+
 def resolve(graph, prices):
     nodes={(r['chain_id'],r['address'].lower()):r for r in graph if r.get('address')}
     known={(r['chain_id'],r['address'].lower()):r for r in prices}
@@ -47,6 +77,8 @@ def resolve(graph, prices):
                 'source':node['source'],'observed_at':node['observed_at'],'block_number':node['block_number'],
                 'curve_price_in_reserve':node['price_in_reserve'],'curve_reserve':node['curve_reserve'],'reserve_symbol':node['reserve_symbol'],
                 'price_path':[node['address']]+parent.get('price_path',[node['reserve_token']])}
+        if parent.get('retained_from_previous'):
+            record.update(retained_from_previous=True,latest_price_status='unavailable',observed_at=parent.get('observed_at'))
         cache[key]=record
         return record
     for key in nodes:visit(key,set())
@@ -69,31 +101,11 @@ def enrich(snapshot,market,folder,deadline=None):
     if recorded.get('market_pending'):raise MarketPause('Reserve checks reached the market time budget. Resume saved checks in Activity.')
     ordinary=[r for r in graph if r.get('address') and r.get('is_curve') is False and r['chain_id'] in ALCHEMY]
     prices=list(market.get('tokens',[]))
-    rejected={(p['chain_id'],p['address'].lower()) for p in prices if p.get('quality')=='unreliable'}
-    ordinary=[r for r in ordinary if (r['chain_id'],r['address'].lower()) not in rejected]
-    # Only reserve assets are requested. Identify prices by network and contract, never symbol.
-    requests=[{'network':ALCHEMY[r['chain_id']],'address':r['address']} for r in ordinary]
-    inverse={value:key for key,value in ALCHEMY.items()}
-    responses=[]
-    key=h.secrets().get('ALCHEMY_CUSTOM_APY_KEY')
-    for i in range(0,len(requests) if key else 0,25):
-        import hashlib
-        batch=requests[i:i+25];identity=hashlib.sha256(json.dumps(batch,sort_keys=True).encode()).hexdigest()
-        file=folder/('reserve-price-cache-'+identity+'.json')
-        record=json.loads(file.read_text()) if file.exists() else None
-        if not record:
-            response=fetch('https://api.g.alchemy.com/prices/v1/'+h.secrets()['ALCHEMY_CUSTOM_APY_KEY']+'/tokens/by-address',{'addresses':batch},deadline=deadline)
-            record={'observed_at':h.now(),'source':'Alchemy token prices by address','request':batch,'response':response}
-            if isinstance(response,dict) and isinstance(response.get('data'),list):atomic(file,record)
-        response=record['response'];responses.append(record)
-        for record in response.get('data') or []:
-            p=next((p for p in record.get('prices',[]) if p.get('currency')=='usd' and p.get('value') is not None),None)
-            if p and not record.get('error'):
-                value=float(p['value'])
-                if math.isfinite(value) and value>0:
-                    prices.append({'chain_id':inverse[record['network']],'address':record['address'],'usd':value,'basis':'Market index','quality':'estimated',
-                                   'observed_at':p.get('lastUpdatedAt'),'source':'https://www.alchemy.com/docs/data/prices-api/prices-api-endpoints/prices-api-endpoints/get-token-prices-by-address'})
-    atomic(folder/'reserve-market-prices.json',responses)
+    settled={(p['chain_id'],p['address'].lower()) for p in prices
+             if p.get('usd') is not None or p.get('quality') in ('unfunded','unreliable')}
+    ordinary=[r for r in ordinary if (r['chain_id'],r['address'].lower()) not in settled]
+    indexed=index_prices([(r['chain_id'],r['address']) for r in ordinary],folder,deadline)
+    prices.extend(indexed['tokens'])
     def get(row):
         chain=DEX.get(row['chain_id'])
         if not chain:return None

package/docs/AGENT_TOOLS.md

@@ -94,6 +94,10 @@ global skill directory. Follow that host's configuration and approval flow.
   `holdings_query` for full-inventory counts, aggregates and rankings instead
   of asking the model to total a truncated page. Query results are bounded to
   25 per page; wallet and historical holdings pages allow up to 100.
+- For price history, call `snapshots_list` with `kind: "prices"` (or `"all"`),
+  then use its IDs with `snapshot_read` and `snapshots_compare`. The default
+  remains holdings history. Each price observation uses its saved overlay and
+  linked holdings; later refreshes cannot replace those selected prices.
 - Report same-symbol ambiguity. Exact identities are chain ID plus contract,
   or `native` for a chain's native asset. Missing records are unknown, not zero.
 - `kira jobs wait ID --timeout 30 --json` waits up to the requested limit

package/docs/CLI.md

@@ -1,9 +1,9 @@
 # CLI and provider configuration
 
-Kira 0.2.1 is a local wallet engine, CLI and web interface. Any capable agent
+Kira is a local wallet engine, CLI and web interface. Any capable agent
 can use the CLI; MCP is optional. Your agent host supplies its own model,
 conversation, general tools and approvals. Kira does not start a model process.
-This branch prepares 0.2.1. Registry publication remains an operator action.
+Version 0.2.2 is published on npm. This source prepares 0.2.3.
 
 ## Install and choose a workspace
 
@@ -35,7 +35,9 @@ use the supported CLI for a consistent data root.
 
 `--json` is accepted anywhere in the command. `info` returns the version,
 data directory, capabilities, connection readiness, saved-data revision, job
-status, UI availability and packaged skill path. Use `--help` for syntax.
+status, UI availability and packaged skill path. Its `research_connection.status`
+is `ready` when Alchemy is connected and `connection_required` before that.
+`--data-dir` also works before or after the subcommand. Use `--help` for syntax.
 
 ## Open the local app
 
@@ -90,7 +92,8 @@ reject the import and preserve the configuration.
 RPC, discovery and import commands apply synchronously when idle. If research
 owns the writer, they return a queued receipt; `--json` always returns a queued
 receipt without waiting. Inspect the resulting job before reporting the
-configuration applied. Safe configuration output contains references, not values.
+configuration applied; its `result.provider_configuration` lists the applied
+modes and reference names. Safe configuration output contains references, not values.
 
 New configurations allow verified public RPC fallback. `--custom-only`
 disables fallback; `--public-fallback` restores it. Existing opt-outs persist.
@@ -122,7 +125,8 @@ kira prices 'Daily wallet' --idempotency-key prices-daily-001 --json
 ```
 
 The first tag is the display name. Exact names and registered addresses select
-wallets. Reuse an idempotency key only when retrying the same intended request.
+wallets. `add` runs the first full holdings lookup itself; use `refresh` for
+later updates. Reuse an idempotency key only when retrying the same intended request.
 
 `add`, `refresh` and `prices` persist a durable job before doing research.
 `--json` or `--enqueue` returns its receipt immediately and starts a separate
@@ -175,10 +179,24 @@ kira call holdings_query --arguments '{"mode":"search","query":"ETH"}' --json
 kira call wallet_read --arguments '{"wallet":"Daily wallet","offset":0,"limit":100}' --json
 kira call token_read --arguments '{"chain_id":8453,"address":"native"}' --json
 kira call snapshots_list --arguments '{"wallet":"Daily wallet","limit":20}' --json
-kira call job_list --arguments '{"state":"running","offset":0,"limit":20}' --json
+kira call snapshots_list --arguments '{"wallet":"Daily wallet","kind":"prices","limit":20}' --json
+kira call job_list --arguments '{"state":"active","offset":0,"limit":20}' --json
 kira ui context --json
 ```
 
+`snapshots_list` defaults to holdings analyses. Use `kind: "prices"` for saved
+price observations or `kind: "all"` for both. Pass the returned IDs to
+`snapshot_read` or `snapshots_compare`. Price observations reproduce their saved
+overlay and keep the linked holdings unchanged, even after another refresh.
+Comparisons include price/value changes and native positions; a price change
+is not a token transfer. No provider request is made by these reads.
+
+`job_list` accepts `state` groups `all` (default), `active` (queued or
+running), `succeeded` (succeeded or partial), `attention` (interrupted or
+failed) and `cancelled`, or one exact state: `queued`, `running`, `partial`,
+`interrupted` or `failed`. Add `wallet` to limit results to one registered
+wallet.
+
 Follow returned `next_offset` values when complete pages are needed. Use
 `holdings_query` for server-computed ranking, counts and aggregates across the
 full inventory. Same-symbol tokens may differ by chain and contract; retain

package/docs/RELEASE.md

@@ -1,6 +1,68 @@
 # Release preparation
 
-## Prepared release: 0.2.1
+## Candidate 0.2.3
+
+Research and price refresh share the Alchemy index fallback and DEX liquidity
+checks. Insufficient or extremely one-sided DEX liquidity stays unpriced;
+provider gaps retain usable prior observations with their original timestamps.
+Cash-out classification uses the same DEX price validation as wallet valuation.
+The symbol-based MEMBER pool override is removed, and a failed curve network
+no longer discards observations from other networks.
+
+History tools accept `snapshots_list` with `kind: "prices"` or `"all"`.
+`snapshot_read` and `snapshots_compare` accept those immutable observation IDs,
+with linked holdings, native positions, independent timestamps and unknowns.
+Price-only refresh also saves evidence when run directly from Python.
+
+OWS registration retries recover the same admitted job after interrupted
+worker launch or receipt storage, including requests saved by 0.2.2. Previously
+registered wallets keep their names, and cancelled jobs remain cancelled.
+Unused embedded-agent completion parsing is removed. The website setup link
+points to the currently published 0.2.2 guide until the next site update.
+
+One independent review of the four audit PRs found a legacy OWS receipt recovery
+gap, corrected with an upgrade regression. Final verification covers the full
+suite, isolated installation, exact archive members, CLI/MCP price history and
+source/history privacy checks. Synthetic checks do not claim live provider or
+Gemini/Grok account acceptance.
+
+Freeze the final archive from the validated, landed source and dry-run that
+exact archive. Release publication and website deployment remain operator
+actions. Preparation does not establish registry publication.
+
+## Published 0.2.2
+
+Fixes two agent contract findings from the published 0.2.1 fresh-agent test.
+`job_list` now publishes its accepted `state` values in the tool schema and
+accepts each exact job state, such as `running`, as well as the existing
+groups. Invalid values return the accepted list. Documented `kira call`
+examples are checked against the published schemas. Global `--data-dir` now
+works before or after a subcommand, like `--json`.
+
+A fresh Claude Code test of this candidate found four more contract gaps, now
+fixed. `research_connection.status` is `ready` only when Alchemy is connected
+and `connection_required` before that, instead of always `configured`. A
+finished settings job reports the settings it applied, not the ones it
+replaced. Native rows in `wallet_read` keep `address: null`, like
+`holdings_query`. `snapshots_list` rows carry `phase`, so progress saved during
+a running lookup is distinct from finished lookups. The skill now explains
+`kira add`, import side effects, per-operation progress, price refresh
+history, float position values and `head_status`.
+
+A second, read-only Claude Code check of the fixed candidate led to three
+more changes. A partial price job now names its reasons in `result.gaps`.
+`kira --help` shows the `kira` program name and a line for every command.
+The skill corrects `head_status`, notes the native `address: null`, the
+100-event job window and older settings receipts. Wallet records, research,
+financial projections and the web app are unchanged.
+
+The operator published 0.2.2 on 2026-10-25. It was frozen from the landed
+merge commit `4c15c69a7e7031a1f52e57d971927abe82fe85f8`. The registry archive is
+byte-identical to the frozen one, SHA-256
+`5d954fc1cb9e679d8f33c94f71721052315e589e4550540e8f5bda10e1ab5089`, and a fresh
+registry install matched all 93 members. Review not selected.
+
+## Published 0.2.1
 
 Includes the external-agent architecture described in the preserved 0.2.0
 candidate below and four approved UI refinements. Short desktop windows can
@@ -9,16 +71,10 @@ one line, a single wallet card fills its available grid width, and token detail
 captions and addresses use larger, darker text. Wallet records, research,
 financial projections, CLI and MCP behavior are unchanged.
 
-Preserve the already frozen 0.2.0 archive and manifest. This 0.2.1 candidate is
-the next publication target; an unpublished earlier candidate is not overwritten.
-Before freezing, run the full repository suite, clean package installation,
-source and history privacy checks, responsive browser acceptance including short
-windows and multiple wallets, and exact source/archive/installed-member checks.
-Freeze from the accepted clean commit, dry-run the exact archive and leave
-registry publication to the operator. Review not selected.
-
-The separate real-device acceptance, fresh public website screenshots and site
-content update remain a follow-up after installation of the new version.
+The operator published 0.2.1. Its archive SHA-256 is
+`aed02bc57c0fec8eec8b8fe8539ddcc45592d7876f04b86045e1d136b51804e0`; the
+installed package and all 93 members matched it. The real-device acceptance
+and website update that followed installation are complete.
 
 ## Preserved candidate: 0.2.0
 
@@ -135,7 +191,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 published GitHub tags, release assets and npm versions through 0.1.20
+Keep published GitHub tags, release assets and npm versions through 0.2.2
 immutable. Do not rebuild them from later documentation commits. Future package
 changes need a new version. Release preparation does not publish a GitHub
 release, promote the website or publish to npm.
@@ -151,12 +207,12 @@ python3 scripts/prepare-release.py
 ```
 
 `prepare-release.py` scans the package boundary and creates
-`dist/kira-wallet-0.2.1.tgz`. The ignored `dist/release.json` records its source
+`dist/kira-wallet-VERSION.tgz` for the version in `package.json`. 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.2.1.tgz --access public
+npm publish ./dist/kira-wallet-VERSION.tgz --access public
 ```
 
 Use the operator's npm account and complete authentication or OTP personally.

package/kira_cli.py

@@ -186,48 +186,51 @@ def finish_configuration(store,job,*,enqueue=False):
     return 0
 
 def main():
-    parser=argparse.ArgumentParser(description=__doc__)
+    parser=argparse.ArgumentParser(prog='kira',description=__doc__)
     parser.add_argument('--version',action='version',version=json.loads((ASSETS/'package.json').read_text())['version'])
     parser.add_argument('--json',action='store_true',help='Return structured output; research commands enqueue without waiting.')
-    parser.add_argument('--data-dir',default=os.environ.get('KIRA_DATA_DIR',str(Path.home()/'.local/share/kira-wallet')))
+    parser.add_argument('--data-dir',default=os.environ.get('KIRA_DATA_DIR',str(Path.home()/'.local/share/kira-wallet')),help='Workspace directory. Accepted before or after the subcommand.')
     sub=parser.add_subparsers(dest='command',required=True)
-    sub.add_parser('init');s=sub.add_parser('start');s.add_argument('--port',type=int,default=8787)
+    sub.add_parser('init',help='Create or check the data directory without changing records.');s=sub.add_parser('start',help='Open the local app.');s.add_argument('--port',type=int,default=8787)
     mode=s.add_mutually_exclusive_group()
     mode.add_argument('--read-only',dest='controls',action='store_false',help='View recorded holdings without local browser actions.')
     mode.add_argument('--controls',dest='controls',action='store_true',help=argparse.SUPPRESS)
     s.set_defaults(controls=True)
     s.add_argument('--no-open',action='store_true',help='Print the local app URL without opening a browser.')
-    setup=sub.add_parser('setup');setup.add_argument('--port',type=int,default=8787);setup.add_argument('--no-open',action='store_true')
-    sub.add_parser('stop');sub.add_parser('status');sub.add_parser('info')
-    wallets=sub.add_parser('wallets');walletsub=wallets.add_subparsers(dest='wallet_action')
+    setup=sub.add_parser('setup',help='Open the local app at first-run setup.');setup.add_argument('--port',type=int,default=8787);setup.add_argument('--no-open',action='store_true')
+    sub.add_parser('stop',help='Stop the local app.');sub.add_parser('status',help='Show whether the local app is running.');sub.add_parser('info',help='Show version, data directory, readiness and active jobs.')
+    wallets=sub.add_parser('wallets',help='List wallets or change their names.');walletsub=wallets.add_subparsers(dest='wallet_action')
     tags=walletsub.add_parser('tags');tags.add_argument('wallet');tags.add_argument('--tag',action='append',required=True);tags.add_argument('--idempotency-key')
-    tools=sub.add_parser('tools');tools.add_argument('--allow-writes',action='store_true')
-    call=sub.add_parser('call');call.add_argument('tool');call.add_argument('--arguments',default='{}')
-    sub.add_parser('skill')
-    ui=sub.add_parser('ui');ui.add_argument('action',choices=['context'])
-    archive=sub.add_parser('archive');archive.add_argument('action',choices=['list','read','workspaces','files','export']);archive.add_argument('conversation',nargs='?');archive.add_argument('--path');archive.add_argument('--output')
-    connection=sub.add_parser('connect');connection.add_argument('provider',choices=['alchemy'])
-    d=sub.add_parser('doctor');d.add_argument('--live',action='store_true');d.add_argument('--chains',default='1,8453,81457');d.add_argument('--budget',type=int,default=30)
-    demo=sub.add_parser('demo');demo.add_argument('--port',type=int,default=8790)
-    add=sub.add_parser('add');add.add_argument('address');add.add_argument('--tag',required=True);add.add_argument('--resume')
-    refresh=sub.add_parser('refresh');refresh.add_argument('wallet');refresh.add_argument('--resume')
-    prices=sub.add_parser('prices');prices.add_argument('wallet')
+    tools=sub.add_parser('tools',help='Serve Kira tools over MCP stdio.');tools.add_argument('--allow-writes',action='store_true')
+    call=sub.add_parser('call',help='Run one Kira tool with JSON arguments.');call.add_argument('tool');call.add_argument('--arguments',default='{}')
+    sub.add_parser('skill',help='Print the agent instructions.')
+    ui=sub.add_parser('ui',help="Read the app's last recorded selection.");ui.add_argument('action',choices=['context'])
+    archive=sub.add_parser('archive',help='Read earlier conversations and generated files.');archive.add_argument('action',choices=['list','read','workspaces','files','export']);archive.add_argument('conversation',nargs='?');archive.add_argument('--path');archive.add_argument('--output')
+    connection=sub.add_parser('connect',help='Enter an Alchemy key at a hidden local prompt.');connection.add_argument('provider',choices=['alchemy'])
+    d=sub.add_parser('doctor',help='Check RPC settings, optionally with live probes.');d.add_argument('--live',action='store_true');d.add_argument('--chains',default='1,8453,81457');d.add_argument('--budget',type=int,default=30)
+    demo=sub.add_parser('demo',help='Open a sample portfolio.');demo.add_argument('--port',type=int,default=8790)
+    add=sub.add_parser('add',help='Register a public wallet and run its first holdings lookup.');add.add_argument('address');add.add_argument('--tag',required=True);add.add_argument('--resume')
+    refresh=sub.add_parser('refresh',help='Run a new holdings lookup for a wallet.');refresh.add_argument('wallet');refresh.add_argument('--resume')
+    prices=sub.add_parser('prices',help='Refresh prices without changing balances.');prices.add_argument('wallet')
     for mutation in (add,refresh,prices):mutation.add_argument('--idempotency-key');mutation.add_argument('--enqueue',action='store_true')
-    jobs=sub.add_parser('jobs');jobsub=jobs.add_subparsers(dest='action',required=True)
+    jobs=sub.add_parser('jobs',help='List, follow and control durable jobs.');jobsub=jobs.add_subparsers(dest='action',required=True)
     jobsub.add_parser('list');jobsub.add_parser('run')
     wait=jobsub.add_parser('wait');wait.add_argument('job_id');wait.add_argument('--timeout',type=float,default=30)
     for action in ('read','resume','cancel','deepen'):
         item=jobsub.add_parser(action);item.add_argument('job_id');item.add_argument('--idempotency-key')
-    config=sub.add_parser('config');configsub=config.add_subparsers(dest='setting',required=True)
+    config=sub.add_parser('config',help='Show settings or import a key file reference.');configsub=config.add_subparsers(dest='setting',required=True)
     configsub.add_parser('show')
     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)
+    rpc=sub.add_parser('rpc',help='Choose public or custom RPC references.');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);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')
+    discovery=sub.add_parser('discovery',help='Choose the token discovery provider.');discovery.add_argument('provider',choices=['none','alchemy']);discovery.add_argument('--key-env',default='ALCHEMY_API_KEY');discovery.add_argument('--explorers',action='store_true')
     argv=sys.argv[1:]
-    # A global machine-output switch works before or after a subcommand.
+    # Global switches work before or after a subcommand.
     if '--json' in argv:argv=['--json']+[a for a in argv if a!='--json']
+    for index,item in enumerate(argv):
+        if item=='--data-dir' and index+1<len(argv):argv=argv[index:index+2]+argv[:index]+argv[index+2:];break
+        if item.startswith('--data-dir='):argv=[item]+argv[:index]+argv[index+1:];break
     args=parser.parse_args(argv);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.')
     if os.name!='posix':raise ValueError('This development build requires a POSIX host. macOS is verified.')

package/kira_config.py

@@ -82,9 +82,10 @@ def public_status(root=None):
     rpc=cfg['rpc'];discovery=cfg['discovery']
     public=rpc['mode']=='public' or rpc['allow_public_fallback']
     import_command=f"kira config import-env --file PATH --key-env {discovery['key_env']}"
-    return {'status':'configured','rpc_mode':rpc['mode'],'read_order':('custom_first' if discovery['provider']=='alchemy' else rpc.get('priority','public_first')) if public else 'custom_only',
+    ready=discovery['provider']=='alchemy' and available
+    return {'status':'ready' if ready else 'connection_required','rpc_mode':rpc['mode'],'read_order':('custom_first' if discovery['provider']=='alchemy' else rpc.get('priority','public_first')) if public else 'custom_only',
             'custom_chain_count':len(rpc['chains']) if rpc['mode']=='custom' else 0,
-            'discovery_provider':discovery['provider'],'discovery_key_available':discovery['provider']=='alchemy' and available,
+            'discovery_provider':discovery['provider'],'discovery_key_available':ready,
             'key_env':discovery['key_env'],'public_discovery':False,'required_provider':'alchemy',
             'import_command':import_command,
             'guide':'Open Workspace settings > Alchemy. Run kira connect alchemy in a terminal and enter the app key at its hidden prompt. Return to Kira to check the connection, then refresh holdings. Actual results establish network access. Never enter or request a key in chat or the browser.',

package/kira_jobs.py

@@ -35,6 +35,10 @@ def signal_process_group(pgid, sig):
 State = Literal['queued', 'running', 'interrupted', 'succeeded', 'partial', 'failed', 'cancelled']
 Operation = Literal['wallet.add','wallet.refresh','prices.refresh','wallet.setTags','settings.rpc','settings.discovery','settings.provider','settings.importEnv']
 TERMINAL = {'succeeded', 'partial', 'failed', 'cancelled', 'interrupted'}
+# Web history uses the groups. Agents may also filter by an exact state they read on a job.
+STATE_FILTERS = {'all': None, 'active': {'queued','running'}, 'succeeded': {'succeeded','partial'},
+                 'attention': {'interrupted','failed'}, 'cancelled': {'cancelled'},
+                 **{state: {state} for state in ('queued','running','partial','interrupted','failed')}}
 ADDRESS = re.compile(r'0x[0-9a-fA-F]{40}')
 
 class Request(TypedDict):
@@ -133,6 +137,11 @@ def fields(value, required):
     if not isinstance(value, dict) or set(value) != set(required):
         raise JobError('invalid_input', 'Unexpected or missing operation fields.')
 
+def provider_summary(config):
+    """Settings facts and environment names only, never values."""
+    return {'rpc_mode':config['rpc']['mode'],'discovery_provider':config['discovery']['provider'],
+            'public_fallback':config['rpc']['allow_public_fallback'],'endpoint_refs':{cid:row['url_env'] for cid,row in config['rpc']['chains'].items()}}
+
 def identifier(value):
     if not isinstance(value, str): raise JobError('invalid_id', 'Expected a job ID.')
     try:
@@ -238,12 +247,10 @@ class JobStore:
     def page(self, offset=0, limit=50, state='all', wallet=None):
         from kira_state import page_bounds
         page_bounds(offset, limit)
-        groups = {'all': None, 'active': {'queued','running'}, 'succeeded': {'succeeded','partial'},
-                  'attention': {'interrupted','failed'}, 'cancelled': {'cancelled'}}
-        if state not in groups:raise JobError('invalid_state','Choose a supported job state filter.')
+        if state not in STATE_FILTERS:raise JobError('invalid_state','Choose a job state filter: '+', '.join(STATE_FILTERS)+'.')
         selected = self.wallet(wallet)['address_key'] if wallet else None
         with self.locked():
-            rows = [r for r in self.summaries() if (groups[state] is None or r['state'] in groups[state])
+            rows = [r for r in self.summaries() if (STATE_FILTERS[state] is None or r['state'] in STATE_FILTERS[state])
                     and (selected is None or (r['input'].get('wallet') or r['input'].get('address','')).lower() == selected)]
             rows.sort(key=lambda r: r['created_at'], reverse=True)
             jobs = [self.get(r['job_id']) for r in rows[offset:offset+limit]]
@@ -483,8 +490,21 @@ class JobStore:
         path = (self.root / snapshot_id).resolve()
         if not path.is_relative_to((self.root / 'snapshots').resolve()) or '..' in Path(snapshot_id).parts:
             raise JobError('invalid_snapshot', 'Snapshot ID is outside saved evidence.')
-        if not (path / 'results.json').is_file(): raise JobError('not_found', 'Snapshot was not found.')
-        result = read(path / 'results.json')
+        if (path / 'results.json').is_file():result = read(path / 'results.json')
+        elif (path / 'prices.json').is_file():
+            overlay=read(path/'prices.json')
+            source=overlay.get('snapshot_id')
+            if not isinstance(source,str) or not source.startswith('snapshots/') or '..' in Path(source).parts:
+                raise JobError('invalid_snapshot','Invalid holdings source for this price observation.')
+            holdings=(self.root/source/'results.json').resolve()
+            if not holdings.is_relative_to((self.root/'snapshots').resolve()) or not holdings.is_file():
+                raise JobError('invalid_snapshot','Price observations require a saved holdings source.')
+            result=read(holdings)
+            if overlay.get('wallet_address','').lower()!=result.get('wallet_address','').lower():
+                raise JobError('wallet_mismatch','Price observation and holdings must belong to the same wallet.')
+            result={**result,'price_observation':{'snapshot_id':snapshot_id,'holdings_snapshot':source,'observed_at':overlay.get('observed_at')},
+                    'price_overlay':{k:overlay[k] for k in ('observed_at','wallet_address','tokens','native_usd','markets','sell_quotes') if k in overlay}}
+        else:raise JobError('not_found', 'Snapshot was not found.')
         # Public readers receive financial facts, never arbitrary raw provider files.
         from kira_config import redact
         def safe(value, key=''):
@@ -503,8 +523,22 @@ class JobStore:
         from decimal import Decimal, InvalidOperation, localcontext
         old, new = self.snapshot(before), self.snapshot(after)
         if old['wallet_address'].lower() != new['wallet_address'].lower():raise JobError('wallet_mismatch','Choose snapshots from the same wallet.')
+        price_comparison=bool(old.get('price_observation') or new.get('price_observation'))
+        valuations=[]
+        if price_comparison:
+            sys.path.insert(0,str(ASSETS/'viewer'))
+            from model import project_wallet
+            entry=self.wallet(old['wallet_address'])
+            for identity,snapshot in ((before,old),(after,new)):
+                source=(snapshot.get('price_observation') or {}).get('holdings_snapshot',identity)
+                projected=project_wallet({**entry,'latest_snapshot':{'directory':source}},snapshot,self.root,market=snapshot.get('price_overlay'))
+                valuations.append({a['id']:a for a in projected['assets']})
         def positions(snapshot):
-            return {(t['chain_id'],t['token_address'].lower(),t.get('token_id')):t for t in snapshot.get('tokens',[])}
+            rows={(t['chain_id'],t['token_address'].lower(),t.get('token_id')):t for t in snapshot.get('tokens',[])}
+            if price_comparison:
+                rows.update({(c['chain_id'],'native',None):{'symbol':c.get('native_symbol'),'wallet_balance':c.get('native_balance')}
+                             for c in snapshot.get('coverage',[])})
+            return rows
         left,right=positions(old),positions(new);changes=[]
         for identity in sorted(left.keys() | right.keys(),key=str):
             a,b=left.get(identity),right.get(identity);delta=None
@@ -523,6 +557,13 @@ class JobStore:
                 'presence':'both' if a and b else 'new_record' if b else 'absent_record',
                 'price_references_changed':(a or {}).get('indexer_price_references')!=(b or {}).get('indexer_price_references'),
                 'valuation_method_changed':bool((a or {}).get('mintclub'))!=bool((b or {}).get('mintclub'))})
+            if price_comparison:
+                first,last=(values.get(str(identity[0])+':'+identity[1],{}) for values in valuations)
+                def price(asset):
+                    return {k:asset['price'].get(k) for k in ('usd','basis','quality','observed_at')} if asset.get('price') else None
+                changes[-1].update(before_price=price(first),after_price=price(last),
+                                   before_value_usd=first.get('value_usd'),after_value_usd=last.get('value_usd'),
+                                   price_references_changed=price(first)!=price(last))
         def counts(rows):
             return {'position_count':len(rows),
                 'new_record_count':sum(r['presence']=='new_record' for r in rows),
@@ -532,20 +573,36 @@ class JobStore:
                 'unchanged_observation_count':sum(r['balance_comparison']=='unchanged_observations' for r in rows),
                 'different_observation_count':sum(r['balance_comparison']=='different_observations' for r in rows),
                 'unknown_comparison_count':sum(r['balance_comparison']=='unknown' for r in rows)}
-        summary={'scope':'full_recorded_non_native_token_comparison_before_pagination',
+        summary={'scope':'full_recorded_price_comparison_before_pagination' if price_comparison else 'full_recorded_non_native_token_comparison_before_pagination',
             'totals':counts(changes),
             'chains':[{'chain_id':cid,**counts([r for r in changes if r['chain_id']==cid])}
                 for cid in sorted({r['chain_id'] for r in changes})]}
         return {'schema_version':1,'before':before,'after':after,'wallet':new['wallet_address'],
-            'coverage_changed':old.get('coverage')!=new.get('coverage'),'price_references_changed':old.get('price_references')!=new.get('price_references'),
-            'comparison_summary':summary,'positions':changes,'note':'Absent records are unknown, not zero. Missing prior or later observations cannot establish or rule out receipts, disposals or transfers. Broader discovery can explain visibility, but activity and its cause remain unknown without transfer history. Even equal observed balances do not exclude intervening activity. Price overlays have separate observations and are not balance changes. Coverage changes compare full evidence, including observation times and blocks; this alone does not prove the set of checked networks changed. Positions compare direct token records. Read both snapshots to compare native balances.'}
+            'coverage_changed':old.get('coverage')!=new.get('coverage'),'price_references_changed':old.get('price_references')!=new.get('price_references') or price_comparison and any(r['price_references_changed'] for r in changes),
+            'comparison_summary':summary,'positions':changes,'note':'Absent records are unknown, not zero. Missing prior or later observations cannot establish or rule out receipts, disposals or transfers. Broader discovery can explain visibility, but activity and its cause remain unknown without transfer history. Even equal observed balances do not exclude intervening activity. Price overlays have separate observations and are not balance changes. Coverage changes compare full evidence, including observation times and blocks; this alone does not prove the set of checked networks changed. ' + ('Positions include native assets and the selected recorded price observations.' if price_comparison else 'Positions compare direct token records. Read both snapshots to compare native balances.')}
 
-    def snapshots(self, wallet):
+    def snapshots(self, wallet, kind='holdings'):
+        if kind not in ('holdings','prices','all'):raise JobError('invalid_snapshot_kind','Choose holdings, prices or all.')
         key = self.wallet(wallet)['address_key']
         paths = {w['latest_snapshot']['directory'] for w in read(self.root / 'wallets.json')['wallets'] if w['address_key'] == key and w.get('latest_snapshot')}
         for run in read(self.root / 'wallets.json').get('research_runs', []):
             if run['address_key'] == key: paths.add(run['snapshot'])
-        return sorted([{'snapshot_id': p, 'compiled_at': self.snapshot(p).get('compiled_at'), 'status': self.snapshot(p).get('status')} for p in paths],key=lambda r:r['compiled_at'] or '')
+        rows = []
+        for path in paths if kind!='prices' else []:
+            # phase "initial" marks progress published while a holdings lookup was still running.
+            snapshot = self.snapshot(path)
+            rows.append({'snapshot_id': path, 'compiled_at': snapshot.get('compiled_at'), 'status': snapshot.get('status'),
+                         'phase': (snapshot.get('pipeline') or {}).get('phase')})
+        if kind!='holdings':
+            evidence=set((self.root/'snapshots/jobs').glob('*/prices.json'))
+            for path in paths:evidence.update((self.root/path/'price-evidence').glob('*/prices.json'))
+            for file in evidence:
+                if not file.resolve().is_relative_to((self.root/'snapshots').resolve()):continue
+                overlay=read(file)
+                if overlay.get('wallet_address','').lower()!=key or overlay.get('snapshot_id') not in paths:continue
+                rows.append({'snapshot_id':str(file.parent.relative_to(self.root)),'compiled_at':overlay.get('observed_at'),
+                             'status':overlay.get('job_result_status'),'phase':'prices','holdings_snapshot':overlay['snapshot_id']})
+        return sorted(rows, key=lambda r: (r['compiled_at'] or '',r['snapshot_id']))
 
     def publication(self, job):
         if job['operation'].startswith('settings.') or job['operation']=='wallet.setTags':
@@ -568,7 +625,8 @@ class JobStore:
             previous = read(projection) if projection.exists() else {}
             value = read(overlay)
             if (previous.get('observed_at') or '') <= value['observed_at']: atomic(projection, value)
-            return {'snapshot_id': item['snapshot_id'], 'overlay': item['overlay'], 'status': item['status']}
+            return {'snapshot_id': item['snapshot_id'], 'overlay': item['overlay'], 'status': item['status'],
+                    **({'gaps': value['job_result_gaps']} if isinstance(value.get('job_result_gaps'), list) else {})}
         manifest = folder / 'run.json'
         if not manifest.exists() or not (folder / 'results.json').exists(): return None
         result = read(folder / 'results.json')
@@ -710,7 +768,8 @@ class JobStore:
                 if job['input']['provider']=='alchemy' and not secret_values(config).get(job['input']['key_env']):
                     raise JobError('connection_key_missing','Kira cannot find the local Alchemy key. Follow the connection guide, then retry. Existing settings are unchanged.')
             atomic(config_path(),config)
-            result={'status':'completed','setting':job['operation']};atomic(self.jobs/'results'/(job['job_id']+'.json'),result);return result
+            result={'status':'completed','setting':job['operation'],'provider_configuration':provider_summary(config)}
+            atomic(self.jobs/'results'/(job['job_id']+'.json'),result);return result
         self.require_connection()
         env = {**os.environ, 'KIRA_DATA_DIR': str(self.root), 'KIRA_JOB_ID': job['job_id'], 'KIRA_JOB_SNAPSHOT': job['checkpoint'], 'KIRA_ANALYSIS_FD': str(writer.fileno()), 'PYTHONUNBUFFERED': '1', 'KIRA_RESEARCH_GENERATION':job.get('parent_job_id',job['job_id'])}
         command=self.engine_command(job)
@@ -815,10 +874,10 @@ class JobStore:
                         if entry.get('research_generation') not in (None,job.get('parent_job_id')):
                             job.update(state='cancelled',stage='stopped',errors=[{'code':'superseded','message':'Newer holdings research replaced this detailed run. Earlier evidence is preserved.'}]);self.save(job);writer.close();continue
                     if job:
-                        from kira_config import load_config
-                        config=load_config()
-                        job['provider_configuration']={'rpc_mode':config['rpc']['mode'],'discovery_provider':config['discovery']['provider'],
-                            'public_fallback':config['rpc']['allow_public_fallback'],'endpoint_refs':{cid:row['url_env'] for cid,row in config['rpc']['chains'].items()}}
+                        # Research records the settings it ran with. Settings jobs report their result instead.
+                        if not job['operation'].startswith('settings.'):
+                            from kira_config import load_config
+                            job['provider_configuration']=provider_summary(load_config())
                         job.update(state='running', stage='starting', started_at=now(), attempt=job['attempt'] + 1, errors=[]); self.save(job)
                 if not job:
                     time.sleep(.5)