kira-wallet 0.2.1 → 0.2.3

package/kira_ows.py

@@ -10,7 +10,7 @@ import shutil
 import subprocess
 import threading
 import uuid
-from kira_jobs import JobError, JobStore, atomic, fields, identifier
+from kira_jobs import JobError, JobStore, atomic, digest, fields, identifier
 
 class OwsStore:
     def __init__(self, root, vault=None, runner=None):
@@ -104,8 +104,14 @@ class OwsStore:
             address=wallet['accounts'][0]['address'];store=JobStore(self.root)
             registered=next((w for w in json.loads((self.root/'wallets.json').read_text())['wallets'] if w['address_key']==address.lower()),None)
             job=None
-            if not registered:
-                job=store.submit({'schema_version':1,'operation':'wallet.add','input':{'address':address,'tag':tag},'idempotency_key':str(uuid.uuid5(uuid.UUID(key),'ows-register'))})
+            registration_key=str(uuid.uuid5(uuid.UUID(key),'ows-register'))
+            # Pre-intent receipts from older versions may already own a queued job.
+            if not registered or receipt.get('registration_requested') or any(j['key_hash']==digest(registration_key) for j in store.list()):
+                # Record intent before admission: submit can register the wallet
+                # before this process has saved its job ID or started a worker.
+                if not receipt.get('registration_requested'):
+                    receipt['registration_requested']=True;atomic(path,receipt)
+                job=store.submit({'schema_version':1,'operation':'wallet.add','input':{'address':address,'tag':tag},'idempotency_key':registration_key})
                 if job['state']=='queued':store.launch()
             connection={'source':'ows','wallet_id':wallet['id'],'name':wallet['name'],'address':address,'tag':(registered.get('tags') or [tag])[0] if registered else tag}
             atomic(self.session,connection);self.session.chmod(0o600)

package/kira_records.py

@@ -4,166 +4,6 @@ import re
 from pathlib import Path
 from kira_jobs import JobError
 
-def read_receipt(name, arguments, result, delivered=True):
-    receipt={'name':name,'arguments':arguments,'status':'completed' if delivered and not (isinstance(result,dict) and result.get('error')) else 'failed'}
-    if name=='portfolio_read' and isinstance(result,dict) and isinstance(result.get('wallets'),list):
-        receipt['wallet_pages']=[read_receipt('inventory_page',{'wallet':w['address'],'offset':w.get('offset',0)},w,receipt['status']=='completed') for w in result['wallets']]
-    if name=='snapshot_read' and isinstance(result,dict) and isinstance(result.get('wallets'),list) and len(result['wallets'])==1:
-        receipt['snapshot_id']=result.get('snapshot_id')
-        result=result['wallets'][0]
-    if isinstance(result,dict):
-        for key in ('offset','next_offset','asset_count','position_count','snapshot_id','query_scope'):
-            if key in result:receipt[key]=result[key]
-        for key in ('assets','positions'):
-            if isinstance(result.get(key),list):receipt['page_end']=result.get('offset',0)+len(result[key])
-    return receipt
-
-def read_completion(message, receipts, tools):
-    """Validate declared plans and literal requests against delivered receipts."""
-    ranking=re.search(r'\btop[- ]*(\d+|one|two|three|four|five|ten)\b|상위\s*(\d+|다섯|열)',message,re.I)
-    requested_rank=None
-    if ranking:
-        raw=next(v for v in ranking.groups() if v).lower()
-        requested_rank=int(raw) if raw.isdigit() else {'one':1,'two':2,'three':3,'four':4,'five':5,'ten':10,'다섯':5,'열':10}[raw]
-    names=set(re.findall(r'\b(?:holdings_query|portfolio_read|wallet_read|snapshot_read|snapshots_compare|token_read|job_read|job_list|snapshots_list)\b',message))
-    literal_names=names.copy()
-    decoder=json.JSONDecoder();requested=[]
-    for match in re.finditer(r'\{',message):
-        try:value,_=decoder.raw_decode(message[match.start():])
-        except ValueError:continue
-        if isinstance(value,dict) and value.get('name',value.get('kira_tool')) in names and isinstance(value.get('arguments'),dict):
-            requested.append((value.get('name',value.get('kira_tool')),value['arguments']))
-    for receipt in receipts:
-        plan=receipt.get('arguments')
-        if receipt['name']=='records_read' and isinstance(plan,dict) and isinstance(plan.get('reads'),list):
-            for read in plan['reads']:
-                if isinstance(read,dict) and isinstance(read.get('name'),str) and isinstance(read.get('arguments'),dict):
-                    names.add(read['name']);requested.append((read['name'],read['arguments']))
-    if not requested_rank and (not names or not requested and not re.search(r'\b(?:read|call|run|use|execute)\b|읽|호출|실행|수행|\+',message,re.I)):return None
-    expanded=[]
-    for receipt in receipts:
-        expanded.extend(receipt.get('reads',[]) if receipt['name']=='records_read' else [receipt])
-    expanded.extend(page for r in list(expanded) for page in r.get('wallet_pages',[]))
-    completed=[r for r in expanded if r['status']=='completed']
-    missing=[name for name in sorted(names) if not any(r['name']==name for r in completed)]
-    if tools and 'wallet_read' in literal_names:
-        context,approved=tools.allowed()
-        wallets=context['wallets']
-        selected=wallets if re.search(r'\b(?:all|each|every)\b|모든|각각|전부',message,re.I) else [w for w in wallets if w['address'].lower() in message.lower() or any(tag.lower() in message.lower() for tag in w['tags'])]
-        actual=set()
-        for receipt in completed:
-            if receipt['name']=='wallet_read':
-                try:actual.add(tools.wallet(receipt['arguments']['wallet'],approved))
-                except JobError:pass
-        missing.extend('wallet_read '+w['name'] for w in selected if w['address'].lower() not in actual)
-    if 'snapshot_read' in names:
-        snapshot_requested=set(re.findall(r'snapshots/[A-Za-z0-9_./-]+',message))
-        actual={r['arguments'].get('snapshot_id') for r in completed if r['name']=='snapshot_read'}
-        missing.extend('snapshot_read '+identity for identity in sorted(snapshot_requested-actual))
-    # Literal JSON read plans are checked by argument, including chain identity.
-    # This is a bounded parser, not a claim to understand every natural request.
-    from kira_research_tools import CATALOG
-    specifications={row['name']:row for row in CATALOG}
-    specifications['inventory_page']={'arguments':{'wallet':None},'optional_arguments':{'offset':None}}
-    def matches(name,wanted,receipt):
-        if receipt['name']!=name:return False
-        if not isinstance(wanted,dict) or not isinstance(receipt.get('arguments'),dict):return False
-        spec=specifications.get(name)
-        if spec is None:return False
-        required=set(spec['arguments']);allowed=required|set(spec.get('optional_arguments',{}))
-        if any(not required<=set(args) or set(args)-allowed for args in (wanted,receipt['arguments'])):return False
-        defaults={'offset':0,'limit':100 if name=='wallet_read' else 20} if name in ('wallet_read','snapshot_read','snapshots_compare') else {}
-        if name=='inventory_page':defaults={'offset':0}
-        wanted={**defaults,**wanted};actual={**defaults,**receipt.get('arguments',{})}
-        if set(wanted)!=set(actual):return False
-        for key,value in wanted.items():
-            other=actual.get(key)
-            if key=='minimum_value_usd':
-                from decimal import Decimal, InvalidOperation
-                try:
-                    left,right=Decimal(str(value)),Decimal(str(other))
-                    if not left.is_finite() or not right.is_finite() or left!=right:return False
-                except InvalidOperation:return False
-                continue
-            if key=='wallet' and tools:
-                try:
-                    _,approved=tools.allowed();value=tools.wallet(value,approved);other=tools.wallet(other,approved)
-                except JobError:return False
-            if isinstance(value,str) and key in ('address','wallet'):value=value.lower();other=other.lower() if isinstance(other,str) else other
-            if type(value) is not type(other) or value!=other:return False
-        return True
-    # A delivered retry fulfils the same request. Keep failed attempts in the
-    # original receipts, but do not call a recovered request incomplete.
-    failed=[{'name':r['name'],'arguments':r.get('arguments',{})} for r in expanded
-            if r['status']=='failed' and r['name']!='inventory_page'
-            and not any(matches(r['name'],r.get('arguments',{}),ok) for ok in completed)]
-    missing.extend(name+' '+json.dumps(args,sort_keys=True) for name,args in requested if not any(matches(name,args,r) for r in completed))
-    if 'token_read' in names and not any(name=='token_read' for name,_ in requested):
-        addresses=set(re.findall(r'0x[0-9a-fA-F]{40}',message))
-        chains={int(value) for value in re.findall(r'\bchain(?:_id)?\s*[:=]?\s*(\d+)\b',message,re.I)}
-        for address in addresses:
-            relevant=[r for r in completed if r['name']=='token_read' and str(r['arguments'].get('address','')).lower()==address.lower()]
-            if not relevant:missing.append('token_read '+address)
-            for chain in chains:
-                if not any(r['arguments'].get('chain_id')==chain for r in relevant):missing.append('token_read '+str(chain)+':'+address)
-    unread=[]
-    exhaustive=bool(re.search(r'\b(?:complete|full)\s+inventory\b|\ball\s+(?:holdings|assets|positions)\b|전체\s*(?:보유|자산|목록)',message,re.I))
-    groups={}
-    for r in expanded:
-        if r['name'] not in ('wallet_read','snapshot_read','snapshots_compare','inventory_page','holdings_query'):continue
-        if r['name']=='holdings_query' and (r.get('query_scope') or {}).get('mode')!='search':continue
-        if not isinstance(r.get('arguments'),dict):continue
-        if r['status']=='failed' and any(matches(r['name'],r.get('arguments',{}),ok) for ok in completed):continue
-        if r['name']=='inventory_page' and not exhaustive:continue
-        identity={k:v for k,v in r['arguments'].items() if k not in ('offset','limit')}
-        if 'wallet' in identity and tools:
-            try:identity['wallet']=tools.wallet(identity['wallet'],tools.allowed()[1])
-            except JobError:pass
-        name='wallet_read' if r['name']=='inventory_page' else r['name']
-        groups.setdefault((name,json.dumps(identity,sort_keys=True),r.get('snapshot_id')),[]).append(r)
-    for (name,identity,snapshot),pages in groups.items():
-        offset=0;seen=set();finished=False
-        while offset not in seen:
-            seen.add(offset);page=next((r for r in pages if r['status']=='completed' and r['arguments'].get('offset',0)==offset and 'next_offset' in r),None)
-            if not page:break
-            if page['next_offset'] is None:finished=True;break
-            if type(page['next_offset']) is not int or page['next_offset']<=offset:break
-            offset=page['next_offset']
-        if not finished and (exhaustive or any(r.get('next_offset') is not None for r in pages)):
-            unread.append({'name':name,'arguments':{**json.loads(identity),'offset':offset},'snapshot_id':snapshot})
-    if requested_rank:
-        from decimal import Decimal
-        ranked=[r for r in completed if r['name']=='holdings_query' and (r.get('query_scope') or {}).get('mode')=='rank']
-        rank_pages={};approved_wallets=None
-        for r in ranked:
-            q=r['query_scope']
-            if not q.get('full_inventory_scanned') or not q.get('complete'):continue
-            identity={'environment':'mainnet','group_by':'asset','query':'',
-                      **{k:v for k,v in r['arguments'].items() if k not in ('offset','limit')}}
-            identity['query']=identity['query'].strip().casefold()
-            if 'minimum_value_usd' in identity:identity['minimum_value_usd']=Decimal(str(identity['minimum_value_usd']))
-            if 'wallet' in identity and tools:
-                try:
-                    if approved_wallets is None:approved_wallets=tools.allowed()[1]
-                    identity['wallet']=tools.wallet(identity['wallet'],approved_wallets)
-                except JobError:continue
-            rank_pages.setdefault((tuple(sorted(identity.items())),q['result_count']),[]).append(q)
-        rank_complete=False
-        for (_,available),pages in rank_pages.items():
-            covered=0
-            for page in sorted(pages,key=lambda q:q['offset']):
-                if page['offset']>covered:break
-                covered=max(covered,page['offset']+page['returned_count'])
-            if covered>=min(requested_rank,available):rank_complete=True;break
-        if not rank_complete:
-            missing.append('holdings_query rank for the requested top '+str(requested_rank))
-    for r in completed:
-        q=r.get('query_scope')
-        if q and not q.get('complete'):missing.append('holdings_query result detail was truncated')
-    missing.extend('holdings_query has unread matching records' for r in unread if r['name']=='holdings_query')
-    if exhaustive:missing.extend(r['name']+' unread offset '+str(r['arguments']['offset']) for r in unread)
-    return {'status':'partial' if missing or failed else 'complete','missing':list(dict.fromkeys(missing)),'failed':failed,'unread_pages':unread,'completed_reads':sum(r['name']!='inventory_page' for r in completed)}
-
 def scoped_wallets(root,config):
     import sys
     sys.path.insert(0,str(Path(__file__).resolve().parent/'viewer'))
@@ -209,7 +49,7 @@ def projection(root, config, *, token_id=None, limit=12, offset=0, wallet_key=No
 def compact_wallet_facts(rows):
     asset_fields=('id','chain_id','address','display_identity','symbol','name','environment','balance','is_native','value_usd','historical_value_usd','balance_observed_at','price','pools','pools_recorded','pools_omitted','exit_quote_recorded','archived')
     return [{**row,'assets':[{key:asset[key] for key in asset_fields if key in asset and
-                           (asset[key] is not None or key in ('value_usd','price'))}
+                           (asset[key] is not None or key in ('address','value_usd','price'))}
                           for asset in row['assets']]} for row in rows]
 
 def recorded_valuation(assets):

package/kira_research_tools.py

@@ -11,7 +11,7 @@ CATALOG = [
     {'name':'wallet_read','arguments':{'wallet':'registered address or exact name'},'optional_arguments':{'offset':'nonnegative integer, default 0','limit':'integer 1 to 100, default 100'},'description':'Read a compact holdings page of one approved wallet. Follow next_offset until null for the complete recorded inventory. Use token_read for curve, market and exit details.'},
     {'name':'holdings_query','arguments':{'mode':'search, rank or aggregate'},'optional_arguments':{'query':'Token symbol, name, exact contract or native. Required for search. Use one query per token.','wallet':'Optional registered wallet name or address; omit for every approved wallet.','chain_id':'Optional positive chain ID','environment':'mainnet (default), testnet or all','group_by':'asset (default: sum priced positions by chain and contract) or position','minimum_value_usd':'Optional nonnegative USD minimum per position; unknowns excluded and counted.','offset':'nonnegative integer, default 0','limit':'integer 1 to 25, default 10'},'description':'Search names, rank top N or aggregate the ENTIRE approved saved inventory on the host. No inventory pagination or jobs needed. Returns exact counts, values, ambiguity and bounded detailed matches. Use search for symbol-only questions, rank for top-N questions and aggregate for counts or sums.'},
     {'name':'token_read','arguments':{'chain_id':'positive integer','address':'contract address or native'},'optional_arguments':{'minimum_value_usd':'Nonnegative USD number or decimal string. Filter by recorded mainnet value; unknowns stay separate.'},'description':'Read this asset across ALL approved wallets in one request, including saved native observations. Use the optional minimum for value-threshold questions and the exact returned position_count. No wallet inventory pagination is needed.'},
-    {'name':'snapshots_list','arguments':{'wallet':'registered address or exact name'},'description':'List past saved analyses for an approved wallet.'},
+    {'name':'snapshots_list','arguments':{'wallet':'registered address or exact name'},'optional_arguments':{'kind':'holdings (default), prices or all'},'description':'List saved holdings analyses or immutable price observations for an approved wallet.'},
     {'name':'snapshot_read','arguments':{'snapshot_id':'saved snapshot ID'},'optional_arguments':{'offset':'nonnegative integer, default 0','limit':'integer 1 to 100, default 20'},'description':'Read a compact page of historical evidence for an approved wallet.'},
     {'name':'snapshots_compare','arguments':{'before':'saved snapshot ID','after':'saved snapshot ID'},'optional_arguments':{'offset':'nonnegative integer, default 0','limit':'integer 1 to 100, default 20'},'description':'Compare a page of recorded positions of the same approved wallet.'},
     {'name':'job_list','arguments':{},'description':'Read research jobs only for approved wallets.'},
@@ -62,21 +62,22 @@ class ResearchTools:
 
     def snapshot(self, identity, approved, offset=0, limit=20):
         # Only published historical analyses listed for this scope may be read.
-        visible={row['snapshot_id'] for key in approved for row in self.store.snapshots(key)}
+        visible={row['snapshot_id'] for key in approved for row in self.store.snapshots(key,kind='all')}
         if identity not in visible:raise JobError('snapshot_scope','This analysis is outside the current conversation scope.')
         result=self.store.snapshot(identity)
         if result.get('wallet_address','').lower() not in approved:raise JobError('snapshot_scope','This analysis does not belong to the approved wallet.')
         from kira_records import wallet_facts, compact_wallet_facts, recorded_valuation
         from model import project_wallet
         entry=self.store.wallet(result['wallet_address'])
-        entry={**entry,'latest_snapshot':{'directory':identity}}
-        wallet=project_wallet(entry,result,self.root);count=len(wallet['assets'])
+        observation=result.get('price_observation')
+        entry={**entry,'latest_snapshot':{'directory':observation['holdings_snapshot'] if observation else identity}}
+        wallet=project_wallet(entry,result,self.root,market=result.get('price_overlay'));count=len(wallet['assets'])
         wallet['recorded_valuation']=recorded_valuation(wallet['assets'])
         wallet['assets']=wallet['assets'][offset:offset+limit]
         rows=compact_wallet_facts(wallet_facts([wallet],pool_budget=0))
         rows[0].update(asset_count=count,assets_omitted=count-len(wallet['assets']),offset=offset,
                        next_offset=offset+len(wallet['assets']) if offset+len(wallet['assets'])<count else None)
-        return {'snapshot_id':identity,'wallets':rows,'note':'Historical recorded evidence. Prices and balances retain their observation times; curve backing is not executable cash. Follow next_offset for more holdings.'}
+        return {'snapshot_id':identity,**({'price_observation':observation} if observation else {}),'wallets':rows,'note':'Historical recorded evidence. Prices and balances retain their observation times; curve backing is not executable cash. Follow next_offset for more holdings.'}
 
     def job(self, job, approved):
         if job['operation'] not in ('wallet.add','wallet.refresh','prices.refresh'):
@@ -159,7 +160,7 @@ class ResearchTools:
             return {'identity':identity,'positions':positions,'position_count':len(positions),'unfiltered_position_count':total,
                     'unpriced_position_count':unpriced,'outside_usd_scope_count':outside,'curve_comparison':compare_curve_states(positions),
                     'note':'An absent record is unknown, not a verified zero holding.'}
-        if name=='snapshots_list':return self.store.snapshots(self.wallet(arguments['wallet'],approved))
+        if name=='snapshots_list':return self.store.snapshots(self.wallet(arguments['wallet'],approved),arguments.get('kind','holdings'))
         if name=='snapshot_read':return self.snapshot(arguments['snapshot_id'],approved,arguments.get('offset',0),arguments.get('limit',20))
         if name=='snapshots_compare':
             self.snapshot(arguments['before'],approved);self.snapshot(arguments['after'],approved)

package/kira_service.py

@@ -4,7 +4,7 @@ import json
 from pathlib import Path
 import time
 import uuid
-from kira_jobs import JobStore, JobError, atomic, fields
+from kira_jobs import JobStore, JobError, atomic, fields, STATE_FILTERS
 from kira_state import StateCache, page, page_bounds
 from kira_research_tools import ResearchTools, CATALOG
 
@@ -18,11 +18,16 @@ for row in CATALOG:
         schema={'type':'integer','minimum':1 if name in ('chain_id','limit') else 0} if name in ('chain_id','offset','limit') else dict(STRING)
         if name=='minimum_value_usd':schema={'type':['string','number']}
         if name=='limit':schema['maximum']=25 if row['name']=='holdings_query' else 100
+        if row['name']=='snapshots_list' and name=='kind':schema['enum']=['holdings','prices','all']
         properties[name]={**schema,'description':description}
     if row['name'] in ('portfolio_read','job_list','snapshots_list'):
         properties.update(offset=INTEGER,limit={'type':'integer','minimum':1,'maximum':100})
-    if row['name']=='job_list':properties.update(state=STRING,wallet=STRING)
-    READ_TOOLS.append({'name':row['name'],'description':row['description'],
+    summary=row['description']
+    if row['name']=='job_list':
+        summary='Read a newest-first page of durable jobs. Optionally filter by state or registered wallet.'
+        properties.update(state={'type':'string','enum':list(STATE_FILTERS),'description':'Default all. Groups: active (queued, running), succeeded (succeeded, partial), attention (interrupted, failed). The other values match one exact state.'},
+                          wallet={**STRING,'description':'registered address or exact name'})
+    READ_TOOLS.append({'name':row['name'],'description':summary,
         'inputSchema':{'type':'object','properties':properties,'required':list(row['arguments']),'additionalProperties':False},
         'annotations':{'readOnlyHint':True,'destructiveHint':False,'idempotentHint':True,'openWorldHint':False}})
 
@@ -63,6 +68,8 @@ def validate(arguments,schema):
         field=schema['properties'][name];types=field['type'] if isinstance(field['type'],list) else [field['type']]
         if not any((type(value) in kinds[k] if isinstance(kinds[k],tuple) else type(value) is kinds[k]) for k in types):
             raise JobError('invalid_input','Invalid argument type: '+name)
+        if 'enum' in field and value not in field['enum']:
+            raise JobError('invalid_input','Choose '+name+' from: '+', '.join(map(str,field['enum']))+'.')
         if isinstance(value,str) and (len(value)>field.get('maxLength',500) or len(value)<field.get('minLength',0)):
             raise JobError('invalid_input','Use a bounded identifier: '+name)
         if type(value) in (int,float) and (value<field.get('minimum',value) or value>field.get('maximum',value)):
@@ -122,7 +129,7 @@ class Application:
             return {'schema_version':1,'dashboard':state['dashboard'],**page(rows,offset,limit,key='wallets'),
                     'data_revision':self.views.revision,'note':'Saved summaries only. Use wallet_read for holdings pages and holdings_query for search, ranking and aggregates.'}
         if name=='snapshots_list':
-            return page(self.jobs.snapshots(arguments['wallet']),arguments.get('offset',0),arguments.get('limit',100),key='snapshots')
+            return page(self.jobs.snapshots(arguments['wallet'],arguments.get('kind','holdings')),arguments.get('offset',0),arguments.get('limit',100),key='snapshots')
         return self.records.call(name,arguments,str(uuid.uuid4()))
 
     def select(self,value):

package/market_records.py

@@ -1,5 +1,7 @@
 """Market identity and public routes. Pool existence never establishes a price."""
+from decimal import Decimal, InvalidOperation
 import json
+import math
 from pathlib import Path
 import re
 from urllib.parse import quote, urlsplit
@@ -9,6 +11,29 @@ NETWORKS={n['chain_id']:n['network'] for n in json.loads((Path(__file__).parent/
 UNISWAP_CHAINS={1:'ethereum',10:'optimism',56:'bnb',137:'polygon',8453:'base',42161:'arbitrum',43114:'avalanche',81457:'blast',130:'unichain',7777777:'zora',4663:'robinhood'}
 
 
+def number(value):
+    try:
+        n = float(Decimal(str(value)))
+        return n if math.isfinite(n) and n >= 0 else None
+    except (InvalidOperation, TypeError, ValueError, OverflowError): return None
+
+MIN_PRICE_LIQUIDITY_USD=1000
+
+def checked_price(price, pools=()):
+    """A spot quote needs a meaningful observed market, including saved quotes."""
+    if not price or price.get('basis')!='DEX market':return price
+    liquidity=number(price.get('liquidity_usd'))
+    if liquidity is None:
+        pool=next((p for p in pools if p.get('source_url')==price.get('source')),None)
+        liquidity=number((pool.get('reported_liquidity') or {}).get('usd')) if pool else None
+        base=number((pool.get('reported_liquidity') or {}).get('base')) if pool else None
+        usd=number(price.get('usd'))
+        if liquidity and base is not None and usd is not None and base*usd/liquidity>0.98:
+            return {**price,'usd':None,'quality':'unreliable','basis':'Insufficient market liquidity','liquidity_usd':liquidity}
+    if liquidity is None or liquidity<MIN_PRICE_LIQUIDITY_USD:
+        return {**price,'usd':None,'quality':'unreliable','basis':'Insufficient market liquidity','liquidity_usd':liquidity}
+    return {**price,'liquidity_usd':liquidity}
+
 def market_url(chain_id, pool):
     """Choose a known venue route without changing the recorded data source."""
     venue=str(pool.get('venue','')).lower()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-wallet",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Local wallet research for your agent session and a human-controlled web workspace.",
   "license": "MIT",
   "private": false,
@@ -104,7 +104,7 @@
     "skills/kira-wallet"
   ],
   "scripts": {
-    "test": "python3 -m unittest discover -s . -p 'test_*.py' && python3 -m unittest discover -s viewer -p 'test_*.py' && node test-onchain.cjs && node test-onchain-continuation.cjs && node test-asset-review.cjs && node test-cashout-quotes.cjs && node test-cashout-routes.cjs && node --check viewer/static/app.js && node --check viewer/static/jobs.js && node test-workspace.cjs && node test-scan-ux.cjs && node --check viewer/static/workspace.js && node --check viewer/static/workspace-model.js && node test-watching.cjs && node test-watching-ui.cjs && node --check viewer/static/watching.js && node --check viewer/static/watching-model.js && node --check viewer/static/report.js && node test-report-ui.cjs && node test-holdings-ui.cjs && node test-settings-ui.cjs && node test-rpc-fallback.cjs && node test-ows.cjs && node test-ows-ui.cjs && node --check viewer/static/ows.js && node --check viewer/static/selects.js && node --check site/demo.js && node test-rpc-pool.cjs && node test-zero-verification.cjs && node test-market-discovery.cjs && node test-sell-quotes.cjs && node test-external-ui.cjs"
+    "test": "python3 -m unittest discover -s . -p 'test_*.py' && python3 -m unittest discover -s viewer -p 'test_*.py' && node test-onchain.cjs && node test-onchain-continuation.cjs && node test-asset-review.cjs && node test-cashout-quotes.cjs && node test-cashout-routes.cjs && node --check viewer/static/app.js && node --check viewer/static/jobs.js && node test-workspace.cjs && node test-scan-ux.cjs && node --check viewer/static/workspace.js && node --check viewer/static/workspace-model.js && node test-watching.cjs && node test-watching-ui.cjs && node --check viewer/static/watching.js && node --check viewer/static/watching-model.js && node --check viewer/static/report.js && node test-report-ui.cjs && node test-holdings-ui.cjs && node test-settings-ui.cjs && node test-rpc-fallback.cjs && node test-ows.cjs && node test-ows-ui.cjs && node --check viewer/static/ows.js && node --check viewer/static/selects.js && node --check site/demo.js && node test-rpc-pool.cjs && node test-zero-verification.cjs && node test-market-discovery.cjs && node test-sell-quotes.cjs && node test-external-ui.cjs && node test-refresh-curve-prices.cjs"
   },
   "dependencies": {
     "viem": "2.57.2"

package/sell_quotes.py

@@ -68,7 +68,7 @@ def candidates(snapshot, market):
             if len(pair) != 2 or address not in pair:
                 continue
             price = output_price(token['chain_id'], next(iter(pair - {address})), market)
-            if not price or price['basis'] == 'DEX market' and (decimal(price.get('liquidity_usd')) or 0) < 1000:
+            if not price:
                 continue
             pools.append(pool)
         if not pools:

package/skills/kira-wallet/SKILL.md

@@ -12,8 +12,9 @@ and MCP operations.
 
 ## Start with the existing workspace
 
-1. Run `kira --version`, then `kira info --json` and inspect readiness and
-   `data_dir`. The commands below require 0.2.0 or later. If installation is
+1. Run `kira --version`, then `kira info --json` and inspect `data_dir` and
+   `research_connection.status`: `ready` means Alchemy is connected;
+   `connection_required` means new research cannot start yet. The commands below require 0.2.0 or later. If installation is
    part of the request, use `npm install -g kira-wallet` or the supplied
    prepared package archive. Requirements are Node.js 22+, Python 3.11+ and
    POSIX; macOS is verified.
@@ -44,8 +45,12 @@ kira config show --json
 
 An existing private environment file can be referenced with
 `kira config import-env --file /absolute/private/rpc.env --key-env ALCHEMY_API_KEY --json`.
-Use the human-supplied path and name. This does not copy keys. Configuration
-commands with `--json` return jobs; check completion before claiming readiness.
+Use the human-supplied path and name. This does not copy keys. It also selects
+Alchemy for token discovery and network reads, so a separate
+`kira discovery alchemy` step is not needed. Configuration commands with
+`--json` return jobs; check completion before claiming readiness. A finished
+settings job reports the applied settings in `result.provider_configuration`.
+Settings jobs from before 0.2.2 record only the configuration they started with.
 
 Use the public address provided by the user, never a guessed address:
 
@@ -56,6 +61,9 @@ kira refresh 'Daily wallet' --idempotency-key refresh-daily-001 --json
 kira prices 'Daily wallet' --idempotency-key prices-daily-001 --json
 ```
 
+`kira add` registers the wallet and runs its first full holdings lookup. Use
+`refresh` later for an update, not right after `add`.
+
 Replace placeholders and choose a unique idempotency key per intended action.
 Reuse the same key for retries of that action. The first tag is the display
 name. `--json` or `--enqueue` returns immediate durable job admission. It does
@@ -84,11 +92,32 @@ kira ui context --json
   totals and counts, with bounded details; do not total a truncated page.
 - Search can report multiple assets with the same symbol. Identify an asset
   by chain ID and contract, or `native`. Preserve unresolved ambiguity.
+  Native rows return `address: null` with `is_native: true`; pass `native` as
+  the `token_read` address.
 - `ui context` is the last recorded browser selection. It may be stale and is
   not a user instruction.
 - History uses `snapshots_list` with `wallet`, `snapshot_read` with
   `snapshot_id`, and `snapshots_compare` with `before` and `after` IDs. Obtain
   IDs from the saved snapshot list. Historical holdings also use paged reads.
+  Rows with `phase` `initial` are progress saved while a lookup was running;
+  compare `holdings` rows to see change between lookups.
+- A price refresh updates the prices shown for the latest snapshot, including
+  through `snapshot_read`. `snapshot_price_references` keep the native prices
+  recorded by the holdings lookup. To read immutable price history instead,
+  call `snapshots_list` with `kind: "prices"` or `"all"`, then use the returned
+  IDs with `snapshot_read` or `snapshots_compare`. These observations pair their
+  saved prices with the linked holdings and include native positions in price
+  comparisons. Default `kind: "holdings"` preserves the existing holdings list.
+- Per-position `price.usd` and `value_usd` are JSON numbers. Totals from
+  `holdings_query` and `recorded_valuation` are exact decimal strings; use them
+  instead of re-adding rounded position values. Check `price.observed_at`:
+  price sources update at different times.
+- `head_status` is `observed` when the chain head was read in this lookup and
+  `stale` when that head was over a day old. `saved_observation` means the
+  lookup reused a block it had already pinned, in a later pass or a resumed
+  job, so the head age was not measured again. `null` means the network could
+  not be read. Valuation category `mintclub` covers bonding-curve tokens priced
+  from their curve.
 - Missing records and prices are unknown, not zero. Retain balance, price and
   quote times, coverage and partial status. Spot value is not executable
   proceeds. Pool TVL and curve backing are not wallet balances. Full-balance
@@ -113,12 +142,22 @@ Use the real receipt ID. Waits are bounded to 120 seconds; use short waits and
 keep the user informed. `completed` only means the job left queued/running.
 Inspect `job.state`, result, errors and coverage before reporting success.
 Partial, interrupted, cancelled and failed states have different meanings.
+Progress events count work per `context.operation`, such as `registry` or
+`balances`. Balance totals grow as the registry scan finds candidates, so do
+not derive one overall percentage. A job's `chains` entries report network
+reads; use `wallet_read` or `network_read` coverage for discovery gaps. A
+partial price job names its reasons in `result.gaps`. Job records keep the
+latest 100 events.
 Accepted work survives viewer shutdown or agent disconnection. Cancel only
 when requested; resume interrupted jobs explicitly. `jobs deepen` adds
 optional sell-route analysis from saved holdings without rediscovering tokens.
 
 Use `call job_list` with optional `state`, `wallet`, `offset` and `limit` for
-paged job discovery. `kira jobs run` starts queued work, not interrupted jobs.
+paged job discovery. `state` is `all` (default), a group (`active`,
+`succeeded`, `attention`, `cancelled`) or an exact state (`queued`, `running`,
+`partial`, `interrupted`, `failed`). `succeeded` includes partial results;
+check `job.state` to separate them.
+`kira jobs run` starts queued work, not interrupted jobs.
 
 ## Shared tools and earlier archives
 

package/viewer/model.py

@@ -5,7 +5,6 @@ from decimal import Decimal, InvalidOperation, localcontext
 from pathlib import Path
 import hashlib
 import json
-import math
 import os
 import re
 from token_images import image_for, read_catalog, safe_image
@@ -13,7 +12,7 @@ from chain_images import chain_image
 from native_assets import native_identity
 from details import project_details
 from sell_quotes import classify_with_cache as cashout_classification
-from market_records import canonical_token, canonical_source, merge_pools, market_url
+from market_records import canonical_token, canonical_source, merge_pools, market_url, number, checked_price, MIN_PRICE_LIQUIDITY_USD
 
 ROOT = Path(os.environ.get('KIRA_DATA_DIR',Path(__file__).resolve().parents[1])).expanduser().resolve()
 EXPLORERS = {1:'https://etherscan.io',8453:'https://basescan.org',81457:'https://blastscan.io',
@@ -26,12 +25,6 @@ EXPLORERS = {1:'https://etherscan.io',8453:'https://basescan.org',81457:'https:/
     157:'https://puppyscan.shib.io',43113:'https://testnet.snowtrace.io'}
 
 def read(path): return json.loads(path.read_text())
-def number(value):
-    try:
-        n = float(Decimal(str(value)))
-        return n if math.isfinite(n) and n >= 0 else None
-    except (InvalidOperation, TypeError, ValueError, OverflowError): return None
-
 def safe_routes(routes):
     result=[]
     if not isinstance(routes,list):return result
@@ -114,23 +107,6 @@ def sell_out_estimate(quote, eligibility, reserve_price):
     return {**quote, 'value_usd': value, 'valuation': 'reserve_reference',
             'output_price': price if usable else None, 'execution_verified': False}
 
-MIN_PRICE_LIQUIDITY_USD=1000
-
-def checked_price(price, pools=()):
-    """A spot quote needs a meaningful observed market, including saved quotes."""
-    if not price or price.get('basis')!='DEX market':return price
-    liquidity=number(price.get('liquidity_usd'))
-    if liquidity is None:
-        pool=next((p for p in pools if p.get('source_url')==price.get('source')),None)
-        liquidity=number((pool.get('reported_liquidity') or {}).get('usd')) if pool else None
-        base=number((pool.get('reported_liquidity') or {}).get('base')) if pool else None
-        usd=number(price.get('usd'))
-        if liquidity and base is not None and usd is not None and base*usd/liquidity>0.98:
-            return {**price,'usd':None,'quality':'unreliable','basis':'Insufficient market liquidity','liquidity_usd':liquidity}
-    if liquidity is None or liquidity<MIN_PRICE_LIQUIDITY_USD:
-        return {**price,'usd':None,'quality':'unreliable','basis':'Insufficient market liquidity','liquidity_usd':liquidity}
-    return {**price,'liquidity_usd':liquidity}
-
 def dex_price(token, observed):
     """Use the selected source observation, never a later publication clock.
 
@@ -161,13 +137,13 @@ def dex_price(token, observed):
             return {'usd':price,'basis':'Market index','source':'https://www.alchemy.com','observed_at':p.get('lastUpdatedAt'),'quality':'estimated'}
     return None
 
-def project_wallet(entry, snapshot, root=ROOT, images=None):
+def project_wallet(entry, snapshot, root=ROOT, images=None, *, market=None):
     images=read_catalog(root) if images is None else images
     latest=entry.get('latest_snapshot') or {}
     snapshot_dir=within(root,latest.get('directory','snapshots'))
     all_networks=snapshot.get('pipeline',{}).get('phase') in ('holdings','sell') or snapshot.get('pipeline',{}).get('holdings_scope')=='all_configured'
     market_path=snapshot_dir/'market-prices.json'
-    market=read(market_path) if market_path.exists() else {}
+    market=(read(market_path) if market_path.exists() else {}) if market is None else market
     prices={(p.get('chain_id',8453),p['address'].lower()):p for p in market.get('tokens',[])}
     recorded_markets={p['id']:p.get('pools',[]) for p in market.get('markets',[])}
     legacy_pools={}

package/viewer/refresh-curve-prices.cjs

@@ -1,36 +1,26 @@
 const fs=require('fs');
 const h=require('../onchain.cjs');
-const {calls}=require('../pipeline-onchain.cjs');
-const file=process.argv[2];
-(async()=>{
- const snapshot=JSON.parse(fs.readFileSync(file));
+const pipeline=require('../pipeline-onchain.cjs');
+async function collect(snapshot){
  const allRows=snapshot.tokens.filter(t=>t.mintclub);
- const output=[];
+ const output=[],errors=[];
  const blocks={};
  for(const chainId of [...new Set(allRows.map(t=>t.chain_id))]){
+ try{
  const rows=allRows.filter(t=>t.chain_id===chainId);
  const c=await h.connect(chainId),block=(await h.snapshotBlock(c)).number;blocks[chainId]=block.toString();
  for(let i=0;i<rows.length;i+=8){
   const batch=rows.slice(i,i+8);
-  const res=await calls(c,batch.map(t=>({address:t.mintclub.bond_address,abi:h.bondAbi,functionName:'getDetail',args:[t.token_address]})),block);
+  const res=await pipeline.calls(c,batch.map(t=>({address:t.mintclub.bond_address,abi:h.bondAbi,functionName:'getDetail',args:[t.token_address]})),block);
   res.forEach((r,j)=>{
    if(r.status==='success'){const v=r.result.info;output.push({chain_id:chainId,address:batch[j].token_address,basis:'Curve spot',curve_price_in_reserve:h.viem.formatUnits(v.priceForNextMint,v.reserveDecimals),curve_reserve:h.viem.formatUnits(v.reserveBalance,v.reserveDecimals),reserve_token:v.reserveToken,reserve_symbol:v.reserveSymbol,funded:v.reserveBalance>0n,source:require('../market-links.cjs').mintclubUrl(chainId,batch[j].symbol,batch[j].token_type||'ERC20'),observed_at:new Date().toISOString(),block_number:block.toString()});}
    else output.push({chain_id:chainId,address:batch[j].token_address,error:h.safeError(r.error)});
   });
  }
+ }catch(error){errors.push({chain_id:chainId,error:h.safeError(error)});}
  }
- // MEMBER is absent from the market index. Read its verified V3 pool price.
- const member=snapshot.tokens.find(t=>t.chain_id===8453&&t.symbol.toLowerCase()==='member');
- if(member){
-  const c=await h.connect(8453),block=(await h.snapshotBlock(c)).number;
-  const pool='0xA4eFE9e8E2A2D5A2aC46805f233b8e49d0e11955';
-  const abi=h.viem.parseAbi(['function slot0() view returns (uint160,int24,uint16,uint16,uint16,uint8,bool)','function token0() view returns (address)','function token1() view returns (address)']);
-  const result=await c.multicall({contracts:['slot0','token0','token1'].map(functionName=>({address:pool,abi,functionName})),multicallAddress:'0xcA11bde05977b3631167028862bE2a173976CA11',batchSize:0,blockNumber:block});
-  if(result.every(r=>r.status==='success')){
-   const ratio=(Number(result[0].result[0])/2**96)**2;
-   const price=result[1].result.toLowerCase()===member.token_address.toLowerCase()?ratio:1/ratio;
-   output.push({chain_id:8453,address:member.token_address,basis:'DEX market',price_in_weth:price,source:'https://basescan.org/address/'+pool,observed_at:new Date().toISOString(),block_number:block.toString()});
-  }
- }
- console.log(h.serialize({observed_at:new Date().toISOString(),blocks,tokens:output}));
-})().catch(e=>{console.log(h.serialize(h.safeError(e)));process.exitCode=1;});
+ return {observed_at:new Date().toISOString(),blocks,tokens:output,errors};
+}
+if(require.main===module)collect(JSON.parse(fs.readFileSync(process.argv[2])))
+ .then(result=>console.log(h.serialize(result))).catch(e=>{console.log(h.serialize(h.safeError(e)));process.exitCode=1;});
+module.exports={collect};