@topolo/cli 0.13.19 → 0.13.21

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

@@ -0,0 +1,397 @@
+"""Owning Claude cloud-dispatch connection, using the existing GUI protocol."""
+import asyncio
+import fcntl
+import hashlib
+import json
+import os
+import pathlib
+import secrets
+import shlex
+import subprocess
+import sys
+import time
+
+from .claude_dispatch import ClaudeBroker
+from .live import request, socket_path
+from .storage import Library, PackError, atomic_json, canonical, read_json
+from .work import require
+
+
+def verify_retired_binding(lib, previous, connection):
+    """A new app process never inherits unresolved native worker custody."""
+    old = previous.get('nativeConnection', {})
+    require(isinstance(old, dict) and set(old) == {'pid', 'runtime', 'identity', 'socket', 'secretPath'}
+            and type(old['pid']) is int and old['pid'] > 1 and old['pid'] == previous.get('desktopPid')
+            and old['pid'] != connection['pid'] and old['runtime'] == connection['runtime']
+            and old['runtime'] == str(lib.root / 'claude/task-runtime'),
+            'Native Desktop connection changed; previous owner identity is unverified')
+    secret = pathlib.Path(old['secretPath'])
+    require(secret.is_relative_to(lib.root / 'claude/journals') and secret.resolve() == secret
+            and not any(parent.is_symlink() for parent in secret.parents) and not secret.is_symlink()
+            and secret.is_file() and secret.stat().st_uid == os.getuid()
+            and not secret.stat().st_mode & 0o077,
+            'Previous native connection secret is not privately owned')
+    try:
+        os.kill(old['pid'], 0)
+    except ProcessLookupError:
+        pass
+    except OSError as exc:
+        raise PackError('Previous Desktop process absence is unverified') from exc
+    else:
+        raise PackError('Previous Desktop process is alive; preserve its worker custody')
+    from .cloud_work import open_store
+    from .work_artifacts import read_checkpoint
+    store = open_store(lib.root)
+    require(getattr(store, 'cloud', False), 'Restart binding requires activated cloud task authority')
+    snapshot = store.snapshot()
+    tasks = {row['id']: row for row in snapshot['tasks']}
+    for worker in snapshot['workers']:
+        task = tasks.get(worker['taskId'])
+        cwd = worker.get('nativePlan', {}).get('cwd', '')
+        if isinstance(cwd, str) and cwd.startswith(old['runtime'] + os.sep):
+            require(os.path.normpath(cwd) == cwd, 'Previous native worker runtime path is ambiguous')
+        owned = isinstance(cwd, str) and pathlib.Path(cwd).is_absolute() and pathlib.Path(cwd).is_relative_to(old['runtime']) and cwd != old['runtime']
+        if not owned:
+            if task and task.get('ownerInstallationId') == store.binding['installationId']:
+                require((worker['state'] == 'archived' and worker.get('nativeArchived') is True)
+                        or (worker['state'] == 'failed' and not worker.get('turnId')
+                            and (not worker.get('nativeId') or worker.get('nativeArchived') is True)),
+                        'Previous historical worker remains active or UNKNOWN; preserve its custody')
+            continue
+        if worker['state']=='failed' and not worker.get('turnId') and (not worker.get('nativeId') or worker.get('nativeArchived') is True):
+            continue
+        require(worker['state'] == 'archived' and worker.get('nativeArchived') is True
+                and worker.get('checkpoint') and worker.get('turnId'),
+                'Previous native worker remains active or UNKNOWN; checkpoint adoption is required')
+        payload = read_checkpoint(store.root, worker['checkpoint'], worker['taskId'], worker['id'])
+        receipt = payload['nativeReceipt']
+        require(payload.get('resolution', {}).get('harness') == 'claude'
+                and payload['phase'] == worker['phase'] and receipt['threadId'] == worker['nativeId']
+                and receipt['turnId'] == worker['turnId'] and receipt['status'] in {'completed', 'failed', 'cancelled'},
+                'Previous native worker terminal checkpoint differs')
+
+
+def verified_predecessor_hook(lib, previous, rows, existing):
+    """Migrate only the exact bound, content-addressed private hook runtime."""
+    require(previous.get('format') == 'topolo-claude-frontdoors-v1'
+            and previous.get('roles') == [
+                {'sessionId': row['sessionId'], 'cwd': row['cwd'],
+                 'channel': {'engineering': 'engineering', 'operator-01': 'operations', 'cicd': 'cicd'}[row['key'].split('/')[-1]]}
+                for row in rows], 'Existing coordinator hook has another owner; preserve it')
+    require(isinstance(existing, list) and len(existing) == 1 and set(existing[0]) == {'hooks'}
+            and isinstance(existing[0]['hooks'], list) and len(existing[0]['hooks']) == 1,
+            'Existing coordinator hook has another owner; preserve it')
+    hook = existing[0]['hooks'][0]
+    require(isinstance(hook, dict) and set(hook) == {'type', 'command', 'timeout'}
+            and hook['type'] == 'command' and hook['timeout'] == 240,
+            'Existing coordinator hook has another owner; preserve it')
+    try:
+        args = shlex.split(hook['command'])
+    except (ValueError, TypeError) as exc:
+        raise PackError('Predecessor hook command is malformed') from exc
+    require(len(args) == 11 and args[0] == sys.executable
+            and args[2:] == ['--store', str(lib.root), 'work', 'claude-hook', '--harness', 'claude', '||', 'exit', '2'],
+            'Predecessor hook command differs from the owned adapter')
+    adapter = pathlib.Path(args[1])
+    runtime = adapter.parent
+    require(adapter.name == 'topolo-agent-pack' and runtime.parent == lib.root / 'claude/hook-runtimes'
+            and len(runtime.name) == 64 and all(c in '0123456789abcdef' for c in runtime.name),
+            'Predecessor hook runtime is outside the owned content-addressed namespace')
+    hashes = {}
+    for path in [runtime, *sorted(runtime.rglob('*'))]:
+        stat = path.lstat()
+        require(not path.is_symlink() and path.resolve() == path and stat.st_uid == os.getuid()
+                and not stat.st_mode & (0o077 if path == runtime else 0o022) and (path.is_dir() or path.is_file()),
+                'Predecessor hook runtime is not privately owned')
+    # The materializer uses localeCompare: underscore sorts before the extension dot.
+    files = [adapter, *sorted((runtime / 'src/topolo_agent_pack').rglob('*.py'),
+                             key=lambda p: str(p.relative_to(runtime)).replace('_', '\x00').replace('.', '\x01'))]
+    caches = {p for p in runtime.rglob('*.pyc') if p.parent.name == '__pycache__'
+              and p.parent.parent == runtime / 'src/topolo_agent_pack'
+              and any(p.name.startswith(source.stem + '.cpython-') for source in files[1:])}
+    require(adapter.is_file() and len(files) > 1
+            and {p for p in runtime.rglob('*') if p.is_file()} == set(files) | caches,
+            'Predecessor hook runtime source closure differs')
+    for path in files:
+        hashes[str(path.relative_to(runtime))] = hashlib.sha256(path.read_bytes()).hexdigest()
+    digest = hashlib.sha256(json.dumps(hashes, separators=(',', ':'), ensure_ascii=False).encode()).hexdigest()
+    require(digest == runtime.name, 'Predecessor hook runtime content digest differs')
+    require(hook['command'] == shlex.join(args[:-3]) + ' || exit 2',
+            'Predecessor hook command encoding differs')
+    return existing
+
+
+def install(root, value):
+    lib = Library(root)
+    require(isinstance(value, dict) and set(value) == {'desktopPid', 'roles', 'nativeConnection'}
+            and type(value['desktopPid']) is int and value['desktopPid'] > 1,
+            'Verified native Desktop process and coordinator sessions required')
+    config = read_json(lib.root / 'work/config.json')
+    require(config.get('format') == 'topolo-task-dispatch-v2' and config.get('requireCloudAuthority') is True,
+            'Install source-independent cloud task authority before Claude dispatch')
+    channels = {'engineering': 'engineering', 'operator-01': 'operations', 'cicd': 'cicd'}
+    rows = value['roles']
+    require(isinstance(rows, list) and len(rows) == 3 and
+            {r.get('key') for r in rows} == {config['pack'] + '/intakes/' + k for k in channels},
+            'Exactly the three installed coordinator roles are required')
+    require(len({r.get('sessionId') for r in rows}) == 3, 'Coordinator SDK session identities must differ')
+    adapter = pathlib.Path(__file__).resolve().parents[2] / 'topolo-agent-pack'
+    require(adapter.is_file(), 'Installed bundled pack entrypoint is unavailable')
+    command = shlex.join([sys.executable, str(adapter), '--store', str(lib.root),
+                         'work', 'claude-hook', '--harness', 'claude']) + ' || exit 2'
+    previous = read_json(lib.root / 'work/claude-frontdoors.json', {})
+    bindings = []
+    for row in rows:
+        require(set(row) == {'key', 'sessionId', 'cwd'} and isinstance(row['sessionId'], str)
+                and row['sessionId'] and pathlib.Path(row['cwd']).is_absolute(), 'Invalid native coordinator binding')
+        cwd = pathlib.Path(row['cwd'])
+        require(cwd.is_relative_to(lib.root / 'claude/workspaces') and cwd.is_dir()
+                and not cwd.is_symlink() and not any(p.is_symlink() for p in cwd.parents),
+                'Front-door hooks require an owned regular Claude workspace')
+        directory = cwd / '.claude'
+        require(not directory.is_symlink(), 'Claude settings directory cannot be a symlink')
+        path = directory / 'settings.json'
+        require(not path.is_symlink(), 'Claude settings cannot be a symlink')
+        settings = read_json(path, {})
+        hooks = settings.get('hooks', {})
+        for event in ['UserPromptSubmit', 'PreToolUse']:
+            existing = hooks.get(event, [])
+            expected = [{'hooks': [{'type': 'command', 'command': command, 'timeout': 240}]}]
+            if existing and existing != expected:
+                verified_predecessor_hook(lib, previous, rows, existing)
+        bindings.append({'sessionId': row['sessionId'], 'cwd': str(cwd),
+                         'channel': channels[row['key'].split('/')[-1]]})
+    from .claude_desktop import call
+    connection = value['nativeConnection']
+    require(isinstance(connection, dict) and set(connection) == {'pid', 'runtime', 'identity', 'socket', 'secretPath'}
+            and connection['pid'] == value['desktopPid']
+            and connection['runtime'] == str(lib.root / 'claude/task-runtime'), 'Exact native Desktop connection required')
+    native = call(connection, {'kind': 'status'})
+    require(native.get('harness') == 'claude-desktop' and native.get('pid') == value['desktopPid']
+            and native.get('identity') == connection['identity'] and native.get('models'),
+            'Signed-in Desktop authentication and model catalog are unavailable')
+    if previous and previous.get('nativeConnection') != connection:
+        verify_retired_binding(lib, previous, connection)
+    process = subprocess.run(['/bin/ps', '-ww', '-p', str(value['desktopPid']), '-o', 'comm='],
+                             capture_output=True, text=True, timeout=5)
+    executable = process.stdout.strip()
+    require(process.returncode == 0 and pathlib.Path(executable).is_absolute()
+            and pathlib.Path(executable).name == 'Claude', 'Verified Claude Desktop executable is unavailable')
+    # Refresh selected cloud role/domain context before exposing any front door.
+    from .role_context import materialize
+    for row in rows:
+        materialize(lib.root / 'work', row['key'], row['cwd'], harness='claude')
+    # Check every destination before changing any hook. The binding is published
+    # first, so a newly observed hook can only dispatch through the selected owner.
+    atomic_json(lib.root / 'work/claude-frontdoors.json',
+                {'format': 'topolo-claude-frontdoors-v1', 'desktopPid': value['desktopPid'],
+                 'nativeConnection': connection,
+                 'desktopExecutable': executable, 'roles': bindings})
+    for row in rows:
+        path = pathlib.Path(row['cwd']) / '.claude/settings.json'
+        settings = read_json(path, {})
+        hooks = settings.setdefault('hooks', {})
+        for event in ['UserPromptSubmit', 'PreToolUse']:
+            hooks[event] = [{'hooks': [{'type': 'command', 'command': command, 'timeout': 240}]}]
+        atomic_json(path, settings)
+        require(read_json(path) == settings, 'Coordinator hook readback differs')
+    return {'state': 'claude-frontdoors-prepared', 'coordinators': 3,
+            'historyRead': False, 'cloudDispatchVerified': False, 'nativePinsChanged': False}
+
+
+class Service:
+    def __init__(self, lib):
+        self.lib = lib
+        self.broker = ClaudeBroker(lib)
+        self.token = secrets.token_hex(32)
+        self.path = socket_path(lib)
+        self.server = None
+        self.desktop_pid = None
+        self.clients = set()
+
+    async def control(self, reader, writer):
+        self.clients.add(writer)
+        try:
+            value = json.loads(await asyncio.wait_for(reader.readline(), 5))
+            require(secrets.compare_digest(value.get('token', ''), self.token), 'Dispatch connection authentication failed')
+            op, params = value.get('operation'), value.get('params') or {}
+            if op == 'status' and not params:
+                result = {'harness': 'claude', 'cloudDispatchReady': True, 'runtime': self.broker.owner.runtime,
+                          'desktopPid': self.desktop_pid,
+                          'activeTurns': [k for k, s in self.broker.sessions.items() if s.assigned and not s.closed],
+                          'workStartupError': None}
+            elif op == 'work-submit': result = await self.broker.submit(params)
+            elif op == 'work-respond': result = await self.broker.respond(params)
+            elif op == 'work-re-review': result = await self.broker.re_review(params)
+            elif op == 'work-list' and not params: result = await self.broker.snapshot()
+            elif op == 'work-read' and set(params) == {'taskId'}: result = await self.broker.read(params['taskId'])
+            elif op == 'work-retained': result = await self.broker.state_call('retained_page', params)
+            elif op == 'work-watch' and not params:
+                await self.broker.watch(reader, writer)
+                return
+            else: raise PackError('Unsupported Claude dispatch operation')
+            writer.write(canonical(result) + b'\n')
+        except Exception as exc:
+            writer.write(canonical({'error': str(exc)}) + b'\n')
+        finally:
+            try:
+                await writer.drain()
+            except (ConnectionError, OSError):
+                pass
+            writer.close()
+            self.clients.discard(writer)
+
+    async def run(self):
+        with (self.lib.root / 'work/claude-service-owner.lock').open('a') as lock:
+            try: fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError as exc: raise PackError('Claude dispatcher already has an owning process') from exc
+            await self.run_owned()
+
+    async def run_owned(self):
+        require(not (self.lib.root / 'work/claude-shutdown-uncertain.json').exists(),
+                'Prior Claude shutdown needs cloud checkpoint reconciliation before startup')
+        await self.broker.initialize()
+        binding = read_json(self.lib.root / 'work/claude-frontdoors.json')
+        pid = binding['desktopPid']
+        self.desktop_pid = pid
+        os.kill(pid, 0)
+        record = self.lib.root / 'live-bridge.json'
+        old = read_json(record, {})
+        if old:
+            try:
+                request(self.lib, 'status', {})
+            except (PackError, OSError):
+                pass
+            else:
+                raise PackError('An owning connection is already live; no competing dispatcher was started')
+        if self.path.exists():
+            require(not self.path.is_symlink() and self.path.stat().st_uid == os.getuid(), 'Unowned dispatch socket')
+            self.path.unlink()
+        self.server = await asyncio.start_unix_server(self.control, path=self.path, limit=1024 * 1024)
+        self.path.chmod(0o600)
+        atomic_json(record, {'socket': str(self.path), 'token': self.token, 'harness': 'claude', 'pid': os.getpid()})
+        self.broker.launch(self.broker.pump())
+        try:
+            while True:
+                await asyncio.sleep(2)
+                try: os.kill(pid, 0)
+                except ProcessLookupError: break
+        finally:
+            self.server.close()
+            # Python 3.13+ waits for accepted clients too. Watch streams must
+            # close before waiting, otherwise a dead Desktop retains custody
+            # forever while an idle GUI is connected.
+            for writer in tuple(self.clients): writer.close()
+            await self.server.wait_closed()
+            for job in list(self.broker.jobs): job.cancel()
+            await asyncio.gather(*self.broker.jobs, return_exceptions=True)
+            closed = await asyncio.gather(*(self.shutdown_session(wid, session)
+                         for wid, session in self.broker.sessions.items()), return_exceptions=True)
+            if read_json(record, {}).get('token') == self.token:
+                record.unlink()
+                self.path.unlink(missing_ok=True)
+            if any(isinstance(result, BaseException) for result in closed):
+                atomic_json(self.lib.root / 'work/claude-shutdown-uncertain.json',
+                            {'state': 'cloud-shutdown-checkpoint-unconfirmed',
+                             'workerIds': list(self.broker.sessions), 'replayAuthorized': False})
+                raise PackError('Claude processes closed; cloud shutdown checkpoint is unconfirmed. Reconcile without replay.')
+
+    async def shutdown_session(self, wid, session):
+        try:
+            if session.assigned and not session.closed:
+                worker = await self.broker.state_call('worker', wid)
+                if worker['state'] != 'archived':
+                    await self.broker.state_call('worker_update', wid,
+                            {'state': 'unknown', 'error': 'Owning Desktop service ended before verified closure.'})
+                    task = await self.broker.state_call('get', worker['taskId'])
+                    await self.broker.state_call('update', task['id'], task['revision'],
+                            {'state': 'unknown', 'summary': 'Owning Desktop service ended; reconcile the existing worker before resuming.'},
+                            'recovery-required')
+        finally:
+            await session.close()
+
+
+def ensure_running(lib):
+    expected_pid = read_json(lib.root / 'work/claude-frontdoors.json').get('desktopPid')
+    require(type(expected_pid) is int and expected_pid > 1, 'Current native Desktop owner binding is required')
+    try:
+        status = request(lib, 'status', {})
+    except (PackError, OSError):
+        status = None
+    if status is not None:
+        require(status.get('harness') == 'claude' and status.get('cloudDispatchReady') is True
+                and status.get('desktopPid') == expected_pid,
+                'Another native owner holds this installation; do not start a competing dispatcher')
+        return
+    lock_path = lib.root / 'work/claude-service-start.lock'
+    with lock_path.open('a') as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX)
+        try:
+            status = request(lib, 'status', {})
+        except (PackError, OSError):
+            status = None
+        if status is not None:
+            require(status.get('harness') == 'claude' and status.get('cloudDispatchReady') is True
+                    and status.get('desktopPid') == expected_pid,
+                    'Another native owner holds this installation')
+            return
+        # Verify cloud activation before spawning a persistent process. There is
+        # no SQLite fallback and an unchanged refusal does not start a retry loop.
+        from .cloud_work import open_store
+        store = open_store(lib.root)
+        require(getattr(store, 'cloud', False), 'Claude requires activated cloud task authority')
+        store.load()
+        env = dict(os.environ)
+        env['PYTHONPATH'] = str(pathlib.Path(__file__).resolve().parent.parent)
+        adapter = pathlib.Path(__file__).resolve().parents[2] / 'topolo-agent-pack'
+        require(adapter.is_file(), 'Installed bundled service entrypoint is unavailable')
+        log = (lib.root / 'work/claude-service.log').open('ab')
+        try:
+            child = subprocess.Popen([sys.executable, str(adapter), '--store', str(lib.root),
+                                      'work', 'serve-claude', '--harness', 'claude'],
+                                     stdin=subprocess.DEVNULL, stdout=log, stderr=log, env=env, start_new_session=True)
+        finally:
+            log.close()
+        deadline = time.monotonic() + 120
+        while child.poll() is None and time.monotonic() < deadline:
+            try:
+                status = request(lib, 'status', {})
+                require(status.get('harness') == 'claude' and status.get('cloudDispatchReady') is True
+                        and status.get('desktopPid') == expected_pid,
+                        'Unexpected owning dispatch connection')
+                return
+            except (PackError, OSError):
+                time.sleep(.1)
+        if child.poll() is None:
+            child.terminate()
+            child.wait(timeout=10)
+        raise PackError('Claude dispatcher did not activate; inspect its owning startup log. No request was submitted.')
+
+
+def refresh_desktop_owner(lib):
+    """Resolve this native hook's Desktop ancestor after an ordinary app restart.
+
+    Uses the executable observed at setup, not a PID cache, version allowlist,
+    browser automation, debugger or local conversation history.
+    """
+    path = lib.root / 'work/claude-frontdoors.json'
+    binding = read_json(path)
+    expected = binding.get('desktopExecutable')
+    require(isinstance(expected, str) and pathlib.Path(expected).is_absolute(),
+            'Verified Desktop executable binding is missing')
+    pid = os.getppid()
+    seen = set()
+    for _ in range(16):
+        require(pid > 1 and pid not in seen, 'This hook has no bound Claude Desktop ancestor')
+        seen.add(pid)
+        observed = subprocess.run(['/bin/ps', '-ww', '-p', str(pid), '-o', 'ppid=', '-o', 'comm='],
+                                  capture_output=True, text=True, timeout=5)
+        fields = observed.stdout.strip().split(None, 1)
+        require(observed.returncode == 0 and len(fields) == 2, 'Native Desktop ancestry is unavailable')
+        if fields[1] == expected:
+            require(binding['desktopPid']==pid and binding.get('nativeConnection',{}).get('pid')==pid,
+                    'Restarted Desktop requires the qualified pack launcher; prior worker custody is preserved')
+            return pid
+        require(fields[0].isdigit(), 'Native parent process identity is invalid')
+        pid = int(fields[0])
+    raise PackError('Native Desktop ancestry exceeds its bounded setup contract')