@topolo/cli 0.12.32 → 0.13.0

package/agent-packs/src/topolo_agent_pack/cli.py

@@ -0,0 +1,416 @@
+"""The topolo-agent-pack command interface and recoverable composition transactions."""
+import argparse
+import copy
+import hashlib
+import json
+import os
+import pathlib
+import selectors
+import shutil
+import sqlite3
+import subprocess
+import sys
+import tempfile
+import time
+import uuid
+
+from . import __version__
+from . import native, live, fresh, blueprint
+from .storage import Library, PackError, atomic_json, canonical, component_key, now, read_json, references, safe_id, select, sync_tree
+
+def emit(value):
+    print(json.dumps(value, indent=2, ensure_ascii=False))
+
+def source_components(manifest, revision, selected):
+    return [{'key':component_key(a),'sourcePack':manifest['packId'],'revision':revision,'originPack':manifest['packId'],'originRevision':revision,'threadId':a['threadId']} for a in selected]
+
+def make_plan(lib, args):
+    active = lib.active(); existing = active.get('components',[])
+    saved=read_json(lib.root/'workbenches'/(safe_id(args.source)+'.json'),{})
+    resume=bool(args.action=='switch' and saved and not getattr(args,'fresh',False))
+    if resume:
+        candidates=[]
+        for c in saved['components']:
+            m,_=lib.load(c['sourcePack'],c['revision'])
+            candidates.extend(a for a in m['agents'] if component_key(a)==c['key'])
+        manifest={'agents':candidates,'warnings':[]}
+        chosen=select(manifest,args.sets,args.agents)
+        incoming=[c for c in saved['components'] if c['key'] in {component_key(a) for a in chosen}]
+        revision='saved-workbench'
+    else:
+        manifest, revision = lib.load(args.source)
+        chosen = select(manifest, args.sets, args.agents)
+        incoming = source_components(manifest,revision,chosen)
+    if args.action=='switch' and active.get('name')==args.source and not args.sets and not args.agents and not getattr(args,'fresh',False):
+        return {'noChange':True,'before':active}
+    before = {c['key']:c for c in existing}
+    selected_keys = {c['key'] for c in incoming}
+    remove = set()
+    if args.action == 'switch': remove = set(before)
+    elif args.action == 'replace':
+        target = getattr(args,'target',None)
+        if target:
+            parts = target.split('/')
+            if not 1 <= len(parts) <= 3: raise PackError('--target must be PACK[/SET[/AGENT]]')
+            for part in parts: safe_id(part)
+            remove = {k for k in before if k == target or k.startswith(target+'/')}
+            if not remove: raise PackError('Replacement target is not in the active composition')
+            if len(parts)==3 and len(incoming)!=1: raise PackError('An individual target accepts exactly one incoming agent')
+            if len(parts)==2 and len({a['set'] for a in chosen})!=1: raise PackError('A set target accepts exactly one incoming set')
+        elif args.agents:
+            remove=selected_keys
+            if not remove <= set(before): raise PackError('Replacement agent is not active; use add or supply --target.')
+        elif args.sets:
+            prefixes={a['pack']+'/'+a['set']+'/' for a in chosen}
+            remove={k for k in before if any(k.startswith(p) for p in prefixes)}
+            if any(not any(k.startswith(p) for k in before) for p in prefixes): raise PackError('Replacement set is not active; use add or supply --target.')
+        else: remove=set(before)
+    elif args.action != 'add': raise PackError('Unknown composition action')
+    remaining={k:v for k,v in before.items() if k not in remove}
+    added=[]
+    for c in incoming:
+        if c['key'] in remaining:
+            old=remaining[c['key']]
+            if old.get('originRevision',old['revision'])==c.get('originRevision',c['revision']) and old.get('originPack',old['sourcePack'])==c.get('originPack',c['sourcePack']): continue
+            raise PackError('add would overwrite an installed identity: '+c['key']+'. Use replace.')
+        remaining[c['key']]=c; added.append(c['key'])
+    components=list(remaining.values())
+    threads=[c['threadId'] for c in components]
+    if len(threads)!=len(set(threads)): raise PackError('Native thread identity collision across selected agents')
+    return {'operation':args.action,'source':args.source,'sourceRevision':revision,'before':active,
+            'components':components,'removed':sorted(remove),'added':added,'noChange':not remove and not added,
+            'name':args.source if args.action=='switch' or not existing else active.get('name',args.source),
+            'resumeRuntime':saved.get('runtime') if resume and not args.sets and not args.agents else None,
+            'reuseOutgoingRuntime':args.action=='switch' and not args.sets and not args.agents,
+            'runtimeCheckpointRequired':bool(existing),'warnings':manifest.get('warnings',[]),
+            'activation':'not tested by plan; --no-open commits storage only'}
+
+def maps(values):
+    result={}
+    for value in values or []:
+        if '=' not in value: raise PackError('--map requires OLD=NEW')
+        old,new=value.split('=',1)
+        old=str(pathlib.Path(old).expanduser().resolve()); new=str(pathlib.Path(new).expanduser().resolve())
+        if not pathlib.Path(new).exists(): raise PackError('Mapped destination does not exist: '+new)
+        if old in result and result[old]!=new: raise PackError('Conflicting path mapping')
+        result[old]=new
+    return result
+
+def verify_backend(lib, runtime, cli):
+    """Read back through the installed native protocol; do not load/resume or start turns."""
+    if not cli: raise PackError('Native Codex binary not found; supply --codex-bin.')
+    cli=pathlib.Path(cli).expanduser().resolve()
+    home=pathlib.Path(runtime)/'home'
+    connection=native.ro(home/'state_5.sqlite')
+    try: expected_cwds=dict(connection.execute('SELECT id,cwd FROM threads'))
+    finally: connection.close()
+    stderr=open(pathlib.Path(runtime)/'backend-verify.log','a')
+    env=os.environ.copy(); env['CODEX_HOME']=str(home)
+    for key in list(env):
+        if key.startswith('CODEX_APP_TOOLS_'): del env[key]
+    proc=subprocess.Popen([str(cli),'app-server','--listen','stdio://'],cwd=runtime,env=env,stdin=subprocess.PIPE,stdout=subprocess.PIPE,stderr=stderr,bufsize=0)
+    sel=selectors.DefaultSelector(); sel.register(proc.stdout,selectors.EVENT_READ)
+    seq=0; buffer=b''
+    def request(method,params):
+        nonlocal seq,buffer
+        seq+=1; proc.stdin.write(canonical({'id':seq,'method':method,'params':params})+b'\n'); proc.stdin.flush()
+        deadline=time.monotonic()+20
+        while time.monotonic()<deadline:
+            while b'\n' in buffer:
+                line,buffer=buffer.split(b'\n',1)
+                if not line.strip(): continue
+                value=json.loads(line)
+                if value.get('id')==seq:
+                    if 'error' in value: raise PackError('Native protocol '+method+': '+value['error']['message'])
+                    return value['result']
+            if not sel.select(max(0,deadline-time.monotonic())): break
+            chunk=os.read(proc.stdout.fileno(),65536)
+            if not chunk: raise PackError('Native verification process exited')
+            buffer+=chunk
+        raise PackError('Native read-back timed out: '+method)
+    checked=[]
+    try:
+        init=request('initialize',{'clientInfo':{'name':'topolo_agent_pack','version':__version__},'capabilities':{'experimentalApi':True}})
+        proc.stdin.write(canonical({'method':'initialized'})+b'\n');proc.stdin.flush()
+        agents=read_json(pathlib.Path(runtime)/'agents.json')['agents']
+        for a in agents:
+            tid=a['threadId']; result=request('thread/read',{'threadId':tid,'includeTurns':False})
+            if result['thread']['id']!=tid: raise PackError('Native thread identity read-back mismatch')
+            expected=str(pathlib.Path(expected_cwds[tid]).resolve())
+            if str(pathlib.Path(result['thread']['cwd']).resolve())!=expected: raise PackError('Native working-directory read-back mismatch for '+tid+': expected '+expected+', got '+result['thread']['cwd'])
+            turns=request('thread/turns/list',{'threadId':tid,'limit':1,'itemsView':'notLoaded'})
+            items=request('thread/items/list',{'threadId':tid,'limit':1})
+            checked.append({'threadId':tid,'cwdVerified':True,'historyReadable':True,'sampledTurns':len(turns['data']),'sampledItems':len(items['data'])})
+    finally:
+        proc.terminate()
+        try: proc.wait(timeout=5)
+        except subprocess.TimeoutExpired: proc.kill(); proc.wait()
+        sel.close(); proc.stdin.close(); proc.stdout.close(); stderr.close()
+    report={'boundary':'native backend read-back; desktop rendering not verified','agents':checked,'modelTurnsStarted':False}
+    atomic_json(pathlib.Path(runtime)/'backend-proof.json',report)
+    return report
+
+def desktop_open(runtime, app, user_data, codex_bin=None):
+    if sys.platform!='darwin': raise PackError('Desktop activation adapter currently supports macOS. Use --no-open for portable storage on this platform.')
+    app=pathlib.Path(app).expanduser().resolve()
+    if not app.is_dir(): raise PackError('Desktop application not found: '+str(app))
+    runtime=pathlib.Path(runtime); user_data=pathlib.Path(user_data); user_data.mkdir(exist_ok=True,mode=0o700)
+    lib=Library(user_data.parent);real=codex_bin or find_codex()
+    executable,home=live.prepare(lib,real)
+    subprocess.run(['/usr/bin/open','-n','--env','CODEX_HOME='+str(home),
+                    '--env','CODEX_CLI_PATH='+str(executable),'--env','CODEX_PACK_HOME='+str(lib.root),
+                    '--env','CODEX_PACK_REAL_CLI='+str(real),
+                    '--env','CODEX_ELECTRON_USER_DATA_PATH='+str(user_data),str(app),
+                    '--args','--user-data-dir='+str(user_data),'--remote-debugging-port=0','--remote-debugging-address=127.0.0.1','codex://launch'],check=True,timeout=20)
+    return {'state':'managed-window-launch-requested','app':str(app),'frontendVerified':False,'note':'One-time managed window launch. Future changes reconnect this same window. Authenticate locally if prompted.'}
+
+def apply_plan(lib,plan,args):
+    if plan['noChange']:
+        active=lib.active()
+        if not args.no_open and not live.available(lib):
+            native.assert_idle(pathlib.Path(active['runtime'])/'home')
+            active['desktop']=desktop_open(active['runtime'],args.app,lib.root/'desktop-data',args.codex_bin)
+            active['state']=active['desktop']['state'];atomic_json(lib.root/'active.json',active)
+            return {'state':active['state'],'active':active}
+        return {'state':'unchanged','active':active}
+    if lib.pending(): raise PackError('An incomplete operation needs recovery. Run topolo-agent-pack recover before another mutation.')
+    before=plan['before']; old_runtime=pathlib.Path(before['runtime']) if before.get('runtime') else None
+    bridge=live.available(lib)
+    if bridge:
+        if not old_runtime or bridge['runtime']!=str(old_runtime): raise PackError('Live bridge and active runtime disagree; run recover before switching')
+        live.adapter(args.app)
+        ws,target=live.renderer(lib);ws.close()
+    elif old_runtime: native.assert_idle(old_runtime/'home')
+    tx=uuid.uuid4().hex; runtime=lib.root/'runtimes'/tx
+    journal={'id':tx,'phase':'started','createdAt':now(),'desktopApp':args.app,'before':before,'operation':plan['operation'],'targetRuntime':str(runtime),'plan':{k:v for k,v in plan.items() if k!='before'}}
+    jpath=lib.root/'journals'/(tx+'.json'); atomic_json(jpath,journal)
+    try:
+        if bridge:
+            journal['liveBridge']={'targetId':target,'beforePid':bridge['pid'],'desktopPid':bridge['desktopPid']};atomic_json(jpath,journal)
+            try:live.quiesce(lib)
+            except Exception:
+                current=live.available(lib)
+                if current and not current['quiesced']:journal['phase']='rolled-back'
+                raise
+            journal['phase']='quiesced';atomic_json(jpath,journal)
+        if old_runtime: native.assert_idle(old_runtime/'home')
+        if bridge:live.checkpoint_ui(lib,old_runtime)
+        if old_runtime and not plan.get('reuseOutgoingRuntime'):
+            known={a['threadId'] for a in read_json(old_runtime/'agents.json')['agents']}
+            if native.unregistered_threads(old_runtime/'home',known):
+                raise PackError('Additional independent threads need registration before partial composition. Run capture NAME --all, then switch NAME --fresh. Whole-pack switches retain these threads in their runtime.')
+        checkpoint_components=copy.deepcopy(before.get('components',[]))
+        if old_runtime:
+            if plan.get('reuseOutgoingRuntime'):
+                # The complete stopped runtime already lives in the independent
+                # pack library. Whole-pack switching can retain it in place.
+                journal['checkpoint']={'mode':'retained-runtime','runtime':str(old_runtime),'components':checkpoint_components}
+            else:
+                checkpoint_name='checkpoint-'+tx
+                snapshot,revision=native.capture(old_runtime/'home',lib,checkpoint_name,all_threads=True,template=read_json(old_runtime/'agents.json'))
+                checkpoint_components=[{**c,'sourcePack':checkpoint_name,'revision':revision} for c in checkpoint_components]
+                journal['checkpoint']={'mode':'immutable-snapshot','pack':checkpoint_name,'revision':revision,'components':checkpoint_components}
+            journal['phase']='checkpointed';atomic_json(jpath,journal)
+            if before.get('name'):
+                atomic_json(lib.root/'workbenches'/(safe_id(before['name'])+'.json'),{**before,'components':checkpoint_components})
+        checkpoint_by_key={c['key']:c for c in checkpoint_components}
+        # Unchanged agents are taken from the current installed state, never the old source template.
+        added=set(plan['added'])
+        target_components=[checkpoint_by_key.get(c['key'],c) if c['key'] not in added else c for c in plan['components']]
+        if plan.get('resumeRuntime'):
+            runtime=pathlib.Path(plan['resumeRuntime']);native.assert_idle(runtime/'home')
+            if args.mappings: raise PackError('Saved workbench paths are already bound. Use --fresh with --map to rebuild.')
+            proof=read_json(runtime/'verification.json')
+            journal['targetRuntime']=str(runtime)
+        else:
+            proof=native.materialize(lib,target_components,runtime,maps(args.mappings))
+            atomic_json(runtime/'composition.json',target_components)
+            # Authentication and local tool configuration are machine-local and
+            # deliberately kept out of portable manifests and export bundles.
+            if old_runtime and (old_runtime/'home'/'auth.json').exists():
+                shutil.copyfile(old_runtime/'home'/'auth.json',runtime/'home'/'auth.json')
+                (runtime/'home'/'auth.json').chmod(0o600)
+            local_config=lib.root/'local-config.toml'
+            if local_config.exists():
+                shutil.copyfile(local_config,runtime/'home'/'config.toml');(runtime/'home'/'config.toml').chmod(0o600)
+        if old_runtime and old_runtime!=runtime and (old_runtime/'desktop-view.json').exists():shutil.copyfile(old_runtime/'desktop-view.json',runtime/'desktop-view.json')
+        journal['phase']='staged';atomic_json(jpath,journal)
+        if old_runtime and old_runtime!=runtime and (old_runtime/'home/auth.json').exists():
+            shutil.copyfile(old_runtime/'home/auth.json',runtime/'home/auth.json');(runtime/'home/auth.json').chmod(0o600)
+        backend=verify_backend(lib,runtime,args.codex_bin)
+        if not plan.get('resumeRuntime'): sync_tree(runtime)
+        if old_runtime: native.assert_idle(old_runtime/'home')
+        if lib.active()!=before: raise PackError('Active composition changed concurrently; refusing to overwrite it.')
+        after={'name':plan['name'],'runtime':str(runtime),'components':target_components,'selectedAt':now(),'state':'backend-verified','desktop':{'state':'not-opened','frontendVerified':False},'transaction':tx}
+        journal['after']=after;journal['phase']='verified';atomic_json(jpath,journal)
+        atomic_json(lib.root/'active.json',after)
+        journal['phase']='committed';atomic_json(jpath,journal)
+        if bridge or not args.no_open:
+            after['desktop']=live.reconnect(lib,runtime,old_runtime,args.app) if bridge else desktop_open(runtime,args.app,lib.root/'desktop-data',args.codex_bin)
+            after['state']=after['desktop']['state'];atomic_json(lib.root/'active.json',after)
+        journal['after']=after;journal['phase']='complete';atomic_json(jpath,journal)
+        return {'state':after['state'],'agents':proof['agents'],'totalHistoryThreads':proof['threads'],'runtime':str(runtime),'checkpoint':journal.get('checkpoint'),
+                'desktop':after['desktop'],'backend':backend,'dependencies':proof['dependencies'],'activeGoalsPaused':proof['activeGoalsPaused']}
+    except Exception as exc:
+        journal['failure']=str(exc);atomic_json(jpath,journal)
+        if bridge and live.available(lib) and live.available(lib).get('quiesced'):
+            try:
+                current=lib.active();journal['reconnectAfterFailure']=live.reconnect(lib,current['runtime'],old_runtime,args.app);atomic_json(jpath,journal)
+            except Exception as reconnect_error:
+                journal['reconnectFailure']=str(reconnect_error);atomic_json(jpath,journal)
+        raise
+
+def recover(lib):
+    result=[]
+    for path in sorted(lib.pending()):
+        j=read_json(path); active=lib.active(); before=j['before']; after=j.get('after')
+        previous=(active.get('runtime')==before.get('runtime') and active.get('transaction')==before.get('transaction') and active.get('components')==before.get('components'))
+        committed=bool(after and active.get('transaction')==j['id'] and active.get('runtime')==after['runtime'] and active.get('components')==after.get('components'))
+        if not previous and not committed:raise PackError('Recovery found a concurrent active-pointer change; no state overwritten. Inspect '+str(path))
+        if j.get('liveBridge'):
+            j['desktopRecovery']=live.reconnect(lib,active['runtime'],before.get('runtime'),j.get('desktopApp','/Applications/ChatGPT.app'))
+            active['desktop']=j['desktopRecovery'];active['state']=active['desktop']['state'];atomic_json(lib.root/'active.json',active)
+        if previous:
+            j['phase']='rolled-back';j['recovery']='Previous active pointer retained; staged files kept for inspection.'
+        elif after and active.get('transaction')==j['id'] and active.get('runtime')==after['runtime']:
+            if not j.get('liveBridge'): native.assert_idle(pathlib.Path(active['runtime'])/'home')
+            if not (pathlib.Path(active['runtime'])/'backend-proof.json').exists(): raise PackError('Committed runtime lacks backend proof; recovery needs inspection.')
+            j['phase']='complete';j['recovery']='Verified committed runtime retained.'+(' Same window reconnected and read back.' if j.get('liveBridge') else ' Desktop activation was not replayed.')
+        else: raise PackError('Recovery found a concurrent active-pointer change; no state overwritten. Inspect '+str(path))
+        atomic_json(path,j);result.append({'transaction':j['id'],'phase':j['phase'],'action':j['recovery']})
+    return {'recovered':result,'active':lib.active()}
+
+def find_codex():
+    bundled=pathlib.Path('/Applications/ChatGPT.app/Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS/codex')
+    return str(bundled) if bundled.exists() else shutil.which('codex')
+
+def parser():
+    p=argparse.ArgumentParser(description='Capture, install and compose portable Topolo Agent Packs. No cloud service or API key required for storage operations.')
+    p.add_argument('--version',action='version',version=__version__)
+    p.add_argument('--store',default=os.environ.get('CODEX_PACK_HOME',str(pathlib.Path.home()/'AgentPacks')))
+    sub=p.add_subparsers(dest='command',required=True)
+    def selection(q):
+        q.add_argument('--set',dest='sets',action='append');q.add_argument('--agent',dest='agents',action='append')
+    def activation(q):
+        q.add_argument('--no-open',action='store_true',help='Commit a backend-verified composition without opening the desktop')
+        q.add_argument('--map',dest='mappings',action='append',help='External path binding OLD=NEW (never overwrites the external destination)')
+        q.add_argument('--codex-bin',default=find_codex());q.add_argument('--app',default='/Applications/ChatGPT.app')
+    cap=sub.add_parser('capture');cap.add_argument('name');selection(cap)
+    cap.add_argument('--source-home',help='Source Codex home. Defaults to the selected managed runtime, otherwise CODEX_HOME or ~/.codex')
+    cap.add_argument('--include',action='append',help='Explicit additional workflow/asset path')
+    cap.add_argument('--all',action='store_true',help='Explicitly capture all non-archived threads when group names do not identify the pack')
+    cap.add_argument('--workspace-mode',choices=['copy','reference'],default='copy')
+    cap.add_argument('--offline',action='store_true',help='Require an idle source instead of taking a read-only live snapshot')
+    q=sub.add_parser('context',help='Extract operating context and conversation rule candidates for review');q.add_argument('source');q.add_argument('directory');selection(q)
+    q=sub.add_parser('fresh',help='Create new native agents from reviewed file-backed context, without old work history');q.add_argument('source');q.add_argument('name');q.add_argument('--context',required=True);selection(q);q.add_argument('--codex-bin',default=find_codex())
+    q=sub.add_parser('build',help='Build a new native instance from a portable authored template; no source pack required');q.add_argument('name');q.add_argument('--template',required=True);selection(q);q.add_argument('--codex-bin',default=find_codex())
+    install=sub.add_parser('install');install.add_argument('bundle');selection(install)
+    export=sub.add_parser('export');export.add_argument('name');export.add_argument('destination')
+    for action in ['add','replace','switch']:
+        q=sub.add_parser(action);q.add_argument('source');selection(q);activation(q)
+        q.set_defaults(action=action)
+        if action=='add': q.add_argument('--catalog',action='store_true',help='Build an uninstalled bundled catalog pack before adding it')
+        if action=='replace': q.add_argument('--target')
+        if action=='switch': q.add_argument('--fresh',action='store_true',help='Use the captured source instead of resuming a previously saved workbench')
+    q=sub.add_parser('plan');q.add_argument('action',choices=['add','replace','switch']);q.add_argument('source');selection(q);q.add_argument('--target');q.add_argument('--fresh',action='store_true')
+    for command in ['connect','remote-context','remember','artifact','artifact-get','remote-recover']:
+        q=sub.add_parser(command,help='Use public Topolo Agent continuity and Bytes artifact contracts')
+        q.add_argument('name');q.add_argument('--environment',choices=['development','staging','production'],required=True)
+        q.add_argument('--context-key',required=True);q.add_argument('--role',required=command not in ['connect','remote-recover'])
+        if command in ['connect','remember','artifact']:q.add_argument('--confirm',action='store_true',required=True)
+        if command=='connect':
+            q.add_argument('--roles',required=True);q.add_argument('--agent-workspace',required=True);q.add_argument('--bytes-workspace',required=True)
+            q.add_argument('--ownership',choices=['user','organization'],required=True);q.add_argument('--bytes-scope',choices=['private','org'],required=True);q.add_argument('--instance')
+        if command=='remember':
+            q.add_argument('--content',required=True);q.add_argument('--kind',choices=['instruction','knowledge','durable'],required=True)
+            q.add_argument('--provenance',required=True);q.add_argument('--visibility',choices=['private','shared'],default='private')
+            q.add_argument('--sharing-policy');q.add_argument('--expires-at',type=int)
+        if command=='artifact':
+            q.add_argument('--file',required=True);q.add_argument('--content-type',default='application/octet-stream')
+            q.add_argument('--visibility',choices=['private','shared'],default='private')
+        if command=='artifact-get':q.add_argument('--reference',required=True);q.add_argument('--destination',required=True)
+    sub.add_parser('status');q=sub.add_parser('list');q.add_argument('name',nargs='?');sub.add_parser('recover')
+    q=sub.add_parser('open');q.add_argument('--codex-bin',default=find_codex());q.add_argument('--app',default='/Applications/ChatGPT.app')
+    q=sub.add_parser('doctor');q.add_argument('name',nargs='?');q.add_argument('--codex-bin',default=find_codex())
+    return p
+
+def main(argv=None):
+    args=parser().parse_args(argv)
+    try:
+        lib=Library(args.store)
+        if args.command in {'connect','remote-context','remember','artifact','artifact-get','remote-recover'}:
+            from . import topolo
+            with topolo.connection_lock(lib,args):result=topolo.dispatch(lib,args)
+            emit(result)
+            return 0
+        with lib.lock():
+            if args.command=='capture':
+                safe_id(args.name)
+                active=lib.active();template=None
+                if args.source_home: home=pathlib.Path(args.source_home)
+                elif active.get('runtime'):
+                    home=pathlib.Path(active['runtime'])/'home';template=read_json(pathlib.Path(active['runtime'])/'agents.json')
+                else: home=pathlib.Path(os.environ.get('CODEX_HOME',str(pathlib.Path.home()/'.codex')))
+                manifest,revision=native.capture(home,lib,args.name,args.sets,args.agents,args.include,args.all,template,args.workspace_mode,live=not args.offline)
+                result={'pack':args.name,'revision':revision,'agents':len(manifest['agents']),'historyThreads':len(manifest['threads']),'warnings':manifest['warnings'],'state':'captured'}
+            elif args.command=='context':result=fresh.prepare(lib,args.source,args.directory,args.sets,args.agents)
+            elif args.command=='fresh':result=fresh.create(lib,args.source,args.name,args.context,args.codex_bin,args.sets,args.agents)
+            elif args.command=='build':result=blueprint.build(lib,args.name,args.template,args.codex_bin,args.sets,args.agents)
+            elif args.command=='install':
+                manifest,revision=lib.install(args.bundle,publish=False)
+                selected=select(manifest,args.sets,args.agents)
+                if args.sets or args.agents:
+                    manifest=native.slice_manifest(lib,manifest,selected)
+                revision=lib.save(manifest)
+                result={'state':'installed-not-activated','pack':manifest['packId'],'revision':revision,'agents':len(selected),'warnings':manifest['warnings']}
+            elif args.command=='export': result=lib.export(args.name,args.destination)
+            elif args.command=='list':
+                if args.name:
+                    manifest,revision=lib.load(args.name)
+                    result={'pack':args.name,'revision':revision,'sets':sorted({a['set'] for a in manifest['agents']}),
+                            'agents':[{'key':component_key(a),'title':a['title'],'aliases':a.get('aliases',[])} for a in manifest['agents']]}
+                else:
+                    result={'packs':[{'name':path.parent.name,'revision':read_json(path)['revision']} for path in sorted((lib.root/'packs').glob('*/head.json')) if not path.parent.name.startswith('checkpoint-')],
+                            'workbenches':[p.stem for p in sorted((lib.root/'workbenches').glob('*.json'))]}
+            elif args.command=='plan': result=make_plan(lib,args)
+            elif args.command in {'add','replace','switch'}:
+                if args.command=='add' and args.catalog and not (lib.root/'packs'/safe_id(args.source)/'head.json').exists():
+                    template=pathlib.Path(__file__).resolve().parents[2]/'templates'/safe_id(args.source)
+                    if not template.is_dir():raise PackError('Unknown catalog pack: '+args.source)
+                    blueprint.build(lib,args.source,template,args.codex_bin)
+                result=apply_plan(lib,make_plan(lib,args),args)
+            elif args.command=='recover': result=recover(lib)
+            elif args.command=='open':
+                active=lib.active()
+                if not active.get('runtime'):raise PackError('Select a pack first with switch NAME')
+                if live.available(lib):result={'state':'already-open','liveBridge':live.available(lib)}
+                else:
+                    native.assert_idle(pathlib.Path(active['runtime'])/'home')
+                    result=desktop_open(active['runtime'],args.app,lib.root/'desktop-data',args.codex_bin)
+                    active['desktop']=result;active['state']=result['state'];atomic_json(lib.root/'active.json',active)
+            elif args.command=='status':
+                active=lib.active();pids=native.busy_writers(pathlib.Path(active['runtime'])/'home') if active.get('runtime') else []
+                result={'store':str(lib.root),'active':active,'liveBridge':live.available(lib),'runtimeDatabaseHolders':pids,'recoveryRequired':[str(p) for p in lib.pending()],'frontendVerified':active.get('desktop',{}).get('frontendVerified',False)}
+            elif args.command=='doctor':
+                checked=[]
+                if args.name:
+                    manifest,revision=lib.load(args.name)
+                    for ref in references(manifest).values(): lib.object(ref)
+                    checked.append({'pack':args.name,'revision':revision,'objectsVerified':len(references(manifest))})
+                result={'library':str(lib.root),'nativeCodex':args.codex_bin,'desktopAdapter':'macOS managed backend proxy and same-window reconnect','liveBridge':live.available(lib),
+                        'recoveryRequired':bool(lib.pending()),'checked':checked,'version':__version__}
+            emit(result)
+        return 0
+    except (PackError,OSError,ValueError,sqlite_error(),subprocess.SubprocessError,zip_error()) as exc:
+        print('topolo-agent-pack: '+str(exc),file=sys.stderr)
+        return 2
+
+def sqlite_error():
+    import sqlite3
+    return sqlite3.Error
+
+def zip_error():
+    import zipfile
+    return zipfile.BadZipFile
+
+if __name__=='__main__': raise SystemExit(main())

package/agent-packs/src/topolo_agent_pack/fresh.py

@@ -0,0 +1,158 @@
+"""Fresh native threads from reviewed portable context; no model calls."""
+import json, os, pathlib, re, selectors, shutil, sqlite3, subprocess, tempfile, time
+from . import native, __version__
+from .storage import PackError, canonical, atomic_json, now, safe_id, select
+
+class Backend:
+    def __init__(self,binary,home,root):
+        if not binary:raise PackError('Native Codex binary is required')
+        env=os.environ.copy();env['CODEX_HOME']=str(home)
+        for k in list(env):
+            if k.startswith('CODEX_APP_TOOLS_'):env.pop(k)
+        self.log=open(root/'seed-backend.log','ab')
+        self.proc=subprocess.Popen([str(binary),'app-server','--listen','stdio://'],cwd=root,env=env,stdin=subprocess.PIPE,stdout=subprocess.PIPE,stderr=self.log,bufsize=0)
+        self.sel=selectors.DefaultSelector();self.sel.register(self.proc.stdout,selectors.EVENT_READ);self.seq=0;self.buffer=b''
+        try:
+            self.call('initialize',{'clientInfo':{'name':'topolo_agent_pack','version':__version__},'capabilities':{'experimentalApi':True}})
+            self.proc.stdin.write(canonical({'method':'initialized'})+b'\n');self.proc.stdin.flush()
+        except BaseException:
+            self.close()
+            raise
+    def call(self,method,params):
+        self.seq+=1;self.proc.stdin.write(canonical({'id':self.seq,'method':method,'params':params})+b'\n');self.proc.stdin.flush();end=time.monotonic()+30
+        while time.monotonic()<end:
+            while b'\n' in self.buffer:
+                line,self.buffer=self.buffer.split(b'\n',1)
+                if not line.strip():continue
+                value=json.loads(line)
+                if value.get('id')==self.seq:
+                    if 'error' in value:raise PackError(method+': '+value['error']['message'])
+                    return value['result']
+            if not self.sel.select(max(0,end-time.monotonic())):break
+            chunk=os.read(self.proc.stdout.fileno(),1024*1024)
+            if not chunk:raise PackError('Native seed backend exited')
+            self.buffer+=chunk
+        raise PackError('Native seed timed out: '+method)
+    def close(self):
+        self.proc.terminate()
+        try:self.proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:self.proc.kill();self.proc.wait()
+        self.sel.close();self.proc.stdin.close();self.proc.stdout.close();self.log.close()
+    def __enter__(self):return self
+    def __exit__(self,*args):self.close()
+
+BASE='Follow the current human request and applicable project instructions. Inspect context, proceed within authorized scope, respect owners and pauses, and verify outcomes. No task is assigned during initialization.\n'
+
+def prepare(lib,source,directory,sets=None,agents=None):
+    m,revision=lib.load(source);chosen=select(m,sets,agents);root=pathlib.Path(directory).expanduser().resolve()
+    if root.exists():raise PackError('Context destination already exists; choose a new directory')
+    root.mkdir(parents=True,mode=0o700)
+    for folder in ['review','agents','shared']:(root/folder).mkdir()
+    common=next((d for d in m['definitions'] if d['relative']=='AGENTS.md'),None)
+    (root/'AGENTS.md').write_text(lib.object(common['content']).read_text() if common else BASE)
+    rule=re.compile(r'\b(always|never|from now on|going forward|whenever|as a rule|each time|must|instructions)\b',re.I);evidence=[]
+    for a in chosen:
+        folder=root/'agents'/a['set']/a['id'];folder.mkdir(parents=True,exist_ok=True)
+        (folder/'AGENTS.md').write_text('# '+a['title']+'\n\nRole: '+a['id']+' (set '+a['set']+').\nOperate within this role and route work outside its authority to the appropriate intake. Read shared operating context before work. Await a new assignment.\n')
+        seen=set();candidates=[];tid=a['threadId'];lineage=[]
+        while tid and tid not in seen:
+            seen.add(tid);lineage.append(tid);tid=m['threads'][tid].get('historyBase')
+        for tid in reversed(lineage):
+            with lib.object(m['threads'][tid]['rollout']).open('rb') as stream:
+                for line in stream:
+                    v=json.loads(line);p=v.get('payload',{})
+                    if v.get('type')!='response_item' or p.get('role')!='user':continue
+                    text='\n'.join(c.get('text','') for c in p.get('content',[]) if isinstance(c,dict))
+                    if text.lstrip().startswith('<') or '# AGENTS.md instructions' in text:continue
+                    for paragraph in text.split('\n\n'):
+                        if 50<len(paragraph)<2000 and rule.search(paragraph):candidates.append({'threadId':tid,'ordinal':v.get('ordinal'),'text':paragraph})
+        candidates=list({c['text']:c for c in candidates}.values())[-30:]
+        atomic_json(root/'review'/(a['set']+'--'+a['id']+'.json'),{'agent':a['id'],'candidates':candidates,'status':'source excerpts; not applied'})
+        evidence.append({'agent':a['id'],'sourceThreadId':a['threadId'],'candidateCount':len(candidates),'sourceWorkingDirectory':m['threads'][a['threadId']]['cwd']})
+    atomic_json(root/'review'/'provenance.json',{'source':source,'revision':revision,'agents':evidence,'createdAt':now()})
+    (root/'README.md').write_text('Edit AGENTS.md and agents/<set>/<agent-id>/AGENTS.md. Put selected portable reference documents in shared/*.md. Review excerpts under review/ and promote only reusable rules into instruction files. Review excerpts and provenance are NEVER loaded into fresh agents. Exclude old assignments, registry/status records, dispatches, leases, credentials and conversation histories. Initial role guides are scaffolds; add the necessary charters before creating a fresh pack.\n')
+    return {'state':'context-extracted-for-review','directory':str(root),'agents':len(chosen),'candidates':sum(e['candidateCount'] for e in evidence),'sourceRevision':revision}
+
+def create(lib,source,name,directory,binary,sets=None,agents=None,authored=None):
+    safe_id(name)
+    if (lib.root/'packs'/name/'head.json').exists():raise PackError('Fresh destination already exists; choose a new name to preserve its work')
+    if lib.pending():raise PackError('Recover the pending operation first')
+    m,revision=authored if authored is not None else lib.load(source)
+    chosen=select(m,sets,agents);context=pathlib.Path(directory).expanduser().resolve();common=context/'AGENTS.md'
+    if not common.is_file() or common.is_symlink():raise PackError('Context requires a regular AGENTS.md')
+    common_text=common.read_text();selected={};presets={}
+    for a in chosen:
+        role=context/'agents'/a['set']/a['id']/'AGENTS.md'
+        if not role.is_file() or role.is_symlink():raise PackError('Missing regular role guide: '+str(role))
+        selected[(a['set'],a['id'])]=role.read_text()
+        preset=role.with_name('config.json')
+        if preset.exists():
+            if preset.is_symlink():raise PackError('Preset must be a regular file')
+            value=json.loads(preset.read_text())
+            if set(value)-{'model','reasoningEffort'} or not isinstance(value.get('model'),str) or value.get('reasoningEffort') not in {'none','minimal','low','medium','high','xhigh','max','ultra'}:raise PackError('Invalid role model preset: '+str(preset))
+            presets[(a['set'],a['id'])]=value
+    shared=[]
+    if (context/'shared').is_symlink():raise PackError('Shared context cannot be a symlink')
+    for f in sorted((context/'shared').rglob('*')):
+        if f.is_symlink():raise PackError('Context symlink is not portable: '+str(f))
+        if f.is_file():
+            if f.suffix!='.md':raise PackError('Shared starting context accepts Markdown only: '+str(f))
+            if f.stat().st_size>1024*1024:raise PackError('Starting reference exceeds 1 MiB: '+str(f))
+            shared.append((f.relative_to(context/'shared'),f.read_bytes()))
+    if len(common_text.encode())+sum(len(v.encode()) for v in selected.values())+sum(len(v) for _,v in shared)>16*1024*1024:raise PackError('Starting context exceeds 16 MiB')
+    root=pathlib.Path(tempfile.mkdtemp(prefix='.fresh-seed-',dir=lib.root));home=root/'home';home.mkdir()
+    try:
+        (home/'AGENTS.md').write_text(common_text);(home/'config.toml').write_text(''.join(k+' = '+json.dumps(v)+'\n' for k,v in m.get('config',{}).items() if k in {'model','model_reasoning_effort','personality'})+'[analytics]\nenabled=false\n')
+        for d in m['definitions']:
+            relative=pathlib.Path(d['relative'])
+            if not relative.parts or relative.parts[0]!='skills':continue
+            if relative.is_absolute() or '..' in relative.parts:raise PackError('Unsafe skill definition')
+            target=home/relative;target.parent.mkdir(parents=True,exist_ok=True);shutil.copyfile(lib.object(d['content']),target)
+        seeded=[];records=[]
+        with Backend(binary,home,root) as b:
+            for a in chosen:
+                workspace=root/'workspaces'/a['set']/a['id'];workspace.mkdir(parents=True)
+                (workspace/'AGENTS.md').write_text(common_text+'\n\n'+selected[(a['set'],a['id'])]+'\n\nStarting references are in context/. Read relevant files before work. No prior assignment or conversation is inherited.\n')
+                for relative,data in shared:
+                    target=workspace/'context'/relative;target.parent.mkdir(parents=True,exist_ok=True);target.write_bytes(data)
+                preset=presets.get((a['set'],a['id']),{})
+                params={'cwd':str(workspace),'historyMode':'paginated','ephemeral':False}
+                if preset:params.update({'model':preset['model'],'config':{'model_reasoning_effort':preset['reasoningEffort']}})
+                result=b.call('thread/start',params);tid=result['thread']['id'];b.call('thread/name/set',{'threadId':tid,'name':a['title']})
+                if preset:b.call('thread/settings/update',{'threadId':tid,'model':preset['model'],'effort':preset['reasoningEffort']})
+                note='Fresh '+a['title']+'. Read AGENTS.md and relevant context/ files for operating instructions. No task is assigned. Wait for a new human request.'
+                b.call('thread/inject_items',{'threadId':tid,'items':[{'type':'message','role':'user','content':[{'type':'input_text','text':note}]}]});b.call('thread/unsubscribe',{'threadId':tid})
+                seeded.append({**a,'pack':name,'threadId':tid});records.append((tid,result['thread']['path'],note))
+        team='# Fresh pack team\n\nResolve peer identities here for human-authorized coordination. Every member starts with no task or claim. This roster grants no external messaging or product effects.\n\n'+'\n'.join('- '+a['set']+'/'+a['id']+' | '+a['title']+' | thread '+a['threadId'] for a in seeded)+'\n'
+        for a in seeded:
+            target=root/'workspaces'/a['set']/a['id']/'context'/'TEAM.md';target.parent.mkdir(parents=True,exist_ok=True);target.write_text(team)
+        # Offline native import adapter. Injected items lack the bootstrap user event
+        # required for desktop discovery. Only this private, stopped seed is edited.
+        db=sqlite3.connect(home/'state_5.sqlite')
+        try:
+            for tid,path,note in records:
+                rollout=pathlib.Path(path);lines=[json.loads(line) for line in rollout.read_bytes().splitlines()];ordinal=max(r.get('ordinal',0) for r in lines)+1
+                with rollout.open('ab') as stream:stream.write(canonical({'timestamp':now(),'ordinal':ordinal,'type':'event_msg','payload':{'type':'user_message','message':note,'images':[],'local_images':[]}})+b'\n')
+                db.execute('UPDATE threads SET has_user_event=1,first_user_message=?,preview=?,memory_mode=? WHERE id=?',(note,note,'disabled',tid))
+            db.commit()
+        finally:db.close()
+        with Backend(binary,home,root) as b:
+            listed=set();cursor=None
+            while True:
+                params={'limit':100}
+                if cursor:params['cursor']=cursor
+                page=b.call('thread/list',params);listed.update(t['id'] for t in page['data']);cursor=page.get('nextCursor')
+                if not cursor:break
+            if not {a['threadId'] for a in seeded}<=listed:raise PackError('Native catalog did not discover every fresh agent')
+            for a in seeded:
+                b.call('thread/read',{'threadId':a['threadId'],'includeTurns':False})
+                if b.call('thread/turns/list',{'threadId':a['threadId'],'limit':1,'itemsView':'notLoaded'})['data']:raise PackError('Fresh seed unexpectedly has turns')
+        manifest,rev=native.capture(home,lib,name,template={'agents':seeded,'dependencies':m.get('dependencies',{})},workspace_mode='copy',live=False)
+        manifest['startingContext']={'kind':'fresh','seedHome':str(home),'sourcePack':source,'sourceRevision':revision,'createdAt':now(),'modelTurnsStarted':False,'previousHistoryCopied':False,'reviewFilesIncluded':False,'memoryMode':'disabled'}
+        if authored is not None:
+            manifest['startingContext']['templateId']=m['packId']
+            manifest['startingContext']['templateVersion']=m['templateVersion']
+            manifest['startingContext']['templateDigest']=revision
+        rev=lib.save(manifest)
+        return {'state':'fresh-pack-created-not-activated','pack':name,'revision':rev,'agents':len(seeded),'nativeCatalogVerified':True,'modelTurnsStarted':False,'previousHistoryCopied':False,'contextDirectory':str(context)}
+    finally:shutil.rmtree(root)