@topolo/cli 0.12.33 → 0.13.1

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

@@ -0,0 +1,92 @@
+"""Portable per-role execution intent, distinct from harness-applied settings.
+
+Rendering a policy never changes a session, permission grant, or pack revision.
+Adapters must independently apply and read back every required setting.
+"""
+import copy
+
+from .storage import PackError, component_key
+
+
+GROUPS = {'specialists': 'Topolo Specialists', 'operators': 'Topolo Operators',
+          'operator-skills': 'Operator Skills'}
+DEEP_ROLES = {'product-direction-01', 'product-direction-02', 'system-architecture-01',
+              'system-architecture-02', 'architecture', 'security-permissions-review',
+              'adversarial-qa', 'incident-triage', 'release-recovery', 'execution-readiness',
+              'privacy-and-agreement-review', 'workflow-integration-specialist',
+              'financial-evidence-specialist', 'accounting-evidence-review',
+              'access-and-privacy'}
+BUILD_ROLES = {'build-01', 'build-02', 'build-03', 'developer-environment-steward',
+               'platform-package-steward', 'worktree-retirement'}
+PROFILES = {
+    'intake': {'tier': 'reasoning', 'effort': 'medium', 'localAccess': 'read-only'},
+    'analysis': {'tier': 'reasoning', 'effort': 'high', 'localAccess': 'read-only'},
+    'review': {'tier': 'workhorse', 'effort': 'high', 'localAccess': 'read-only'},
+    'build': {'tier': 'workhorse', 'effort': 'high', 'localAccess': 'workspace-write'},
+    'operator': {'tier': 'workhorse', 'effort': 'medium', 'localAccess': 'workspace-write'},
+}
+MODELS = {'codex': {'reasoning': 'gpt-6-astra', 'workhorse': 'gpt-6.1-sol'},
+          'claude': {'reasoning': 'claude-opus-5-5', 'workhorse': 'claude-sonnet-5-5'}}
+
+
+def role_profile(agent):
+    explicit = agent.get('executionProfile')
+    if explicit is not None:
+        if explicit not in PROFILES:
+            raise PackError('Unknown execution profile for ' + component_key(agent))
+        return explicit
+    if agent['set'] == 'intakes':
+        return 'intake'
+    if agent['id'] in DEEP_ROLES:
+        return 'analysis'
+    if agent['id'] in BUILD_ROLES:
+        return 'build'
+    if agent['set'] == 'specialists':
+        return 'review'
+    return 'operator'
+
+
+def settings(agent, harness):
+    if harness not in MODELS:
+        raise PackError('Execution settings adapter is not qualified: ' + harness)
+    profile = role_profile(agent)
+    spec = PROFILES[profile]
+    model = MODELS[harness][spec['tier']]
+    if harness == 'codex':
+        native = {'model': model, 'model_reasoning_effort': spec['effort'],
+                  'approval_policy': 'on-request', 'approvals_reviewer': 'user',
+                  'sandbox_mode': spec['localAccess'],
+                  'sandbox_workspace_write': {'network_access': False, 'writable_roots': [],
+                                              'exclude_slash_tmp': True, 'exclude_tmpdir_env_var': True},
+                  'apps': {'_default': {'default_tools_approval_mode': 'writes'}}}
+    else:
+        native = {'model': model, 'effortLevel': spec['effort'],
+                  'permissions': {'defaultMode': 'acceptEdits' if profile == 'build' else 'default'}}
+    return {'profile': profile, 'nativeSettings': native,
+            'localAccessIntent': spec['localAccess'], 'applied': False,
+            # Claude Manual is an approval mode, not a read-only filesystem sandbox.
+            'requiresAdditionalLocalConfinement': harness == 'claude' and spec['localAccess'] == 'read-only'}
+
+
+def render(manifest, revision, agents, harnesses=('codex', 'claude')):
+    rows = []
+    for agent in agents:
+        rows.append({'key': component_key(agent), 'title': agent['title'],
+                     'sidebar': {'group': GROUPS.get(agent['set'], agent['set']),
+                                 'pinned': agent.get('pinned', False)},
+                     'harnesses': {h: settings(agent, h) for h in harnesses}})
+    return {'format': 'topolo-agent-execution-policy', 'schemaVersion': 1,
+            'pack': manifest['packId'], 'sourceRevision': revision, 'agents': rows,
+            'applied': False,
+            'contextPolicy': {'load': ['role charter', 'current task', 'relevant retrieved memory'],
+                              'sharedMemory': 'retrieve by task and user or organization scope',
+                              'history': 'preserve, do not copy between roles',
+                              'skills': 'load on demand', 'toolResults': 'bounded relevant excerpts',
+                              'idleModelTurns': False, 'backgroundPolling': False,
+                              'handoffs': 'one concise outcome with evidence references'},
+            'verification': {'required': ['session identity', 'sidebar membership', 'pins',
+                                          'model', 'effort', 'permissions', 'context identity'],
+                             'unsupportedSettings': 'refuse activation; never silently substitute'},
+            'authority': {'externalActions': 'existing human authorization and platform access controls',
+                          'packMembershipGrantsAuthority': False},
+            'profiles': copy.deepcopy(PROFILES)}

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

@@ -0,0 +1,271 @@
+"""Immutable portable library, checked object storage, and durable transactions."""
+import contextlib
+import fcntl
+import hashlib
+import json
+import os
+import pathlib
+import re
+import tempfile
+import time
+import uuid
+import zipfile
+
+class PackError(Exception):
+    pass
+
+def safe_id(value):
+    if not re.fullmatch(r"[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}", value) or value in {".", ".."}:
+        raise PackError(f"Invalid identifier: {value!r}")
+    return value
+
+def slug(value):
+    result = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
+    return result[:110] or "agent"
+
+def canonical(value):
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
+
+def now():
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+def read_json(path, default=None):
+    path = pathlib.Path(path)
+    if not path.exists() and default is not None:
+        return default
+    return json.loads(path.read_text())
+
+def sync_directory(path):
+    fd=os.open(path,os.O_RDONLY)
+    try: os.fsync(fd)
+    finally: os.close(fd)
+
+def sync_tree(root):
+    """Flush staged native files before publishing the durable active pointer."""
+    for folder,dirs,files in os.walk(root,followlinks=False):
+        for name in files:
+            path=pathlib.Path(folder)/name
+            if path.is_symlink(): continue
+            with path.open('rb') as stream: os.fsync(stream.fileno())
+        sync_directory(folder)
+
+def atomic_json(path, value):
+    path = pathlib.Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    fd, tmp = tempfile.mkstemp(prefix=".pending-", dir=path.parent)
+    try:
+        with os.fdopen(fd, "wb") as stream:
+            stream.write(canonical(value) + b"\n")
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+        dirfd = os.open(path.parent, os.O_RDONLY)
+        try:
+            os.fsync(dirfd)
+        finally:
+            os.close(dirfd)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+
+class Library:
+    def __init__(self, root):
+        self.root = pathlib.Path(root).expanduser().resolve()
+        self.root.mkdir(parents=True, exist_ok=True, mode=0o700)
+        for name in ["objects", "packs", "runtimes", "journals"]:
+            (self.root / name).mkdir(exist_ok=True, mode=0o700)
+
+    @contextlib.contextmanager
+    def lock(self):
+        with (self.root / ".lock").open("a+") as stream:
+            os.chmod(stream.name, 0o600)
+            try:
+                fcntl.flock(stream, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError:
+                raise PackError("Another topolo-agent-pack operation owns this library. Retry after it finishes.")
+            yield
+
+    def put(self, source, limit=None):
+        if limit is not None and (not isinstance(limit,int) or limit<0): raise PackError('Invalid capture byte boundary')
+        digest = hashlib.sha256()
+        fd, temp = tempfile.mkstemp(dir=self.root / "objects", prefix=".capture-")
+        size = 0
+        try:
+            with os.fdopen(fd, "wb") as dest:
+                if isinstance(source, bytes):
+                    digest.update(source); dest.write(source); size = len(source)
+                else:
+                    source = pathlib.Path(source)
+                    before = source.stat()
+                    with source.open("rb") as stream:
+                        while chunk := stream.read(min(1024*1024,limit-size) if limit is not None else 1024*1024):
+                            digest.update(chunk); dest.write(chunk); size += len(chunk)
+                    after = source.stat()
+                    changed=(before.st_size,before.st_mtime_ns,before.st_ino)!=(after.st_size,after.st_mtime_ns,after.st_ino)
+                    if limit is not None:
+                        changed=before.st_ino!=after.st_ino or size!=limit or after.st_size<limit
+                    if changed:
+                        raise PackError(f"File changed during capture: {source}")
+                dest.flush(); os.fsync(dest.fileno())
+            key = digest.hexdigest()
+            target = self.root / "objects" / key
+            if not target.exists():
+                os.chmod(temp, 0o600); os.replace(temp, target)
+                sync_directory(target.parent)
+            else: self.object({'sha256':key,'bytes':size})
+            return {"sha256": key, "bytes": size}
+        finally:
+            if os.path.exists(temp):
+                os.unlink(temp)
+
+    def object(self, ref, verify=True):
+        key = ref.get("sha256", "")
+        if not re.fullmatch(r"[a-f0-9]{64}", key):
+            raise PackError("Invalid object digest in pack")
+        path = self.root / "objects" / key
+        if not path.is_file() or path.is_symlink():
+            raise PackError(f"Missing object: {key}")
+        if verify:
+            h = hashlib.sha256()
+            with path.open("rb") as f:
+                while chunk := f.read(1024 * 1024): h.update(chunk)
+            if h.hexdigest() != key or path.stat().st_size != ref["bytes"]:
+                raise PackError(f"Corrupt object: {key}")
+        return path
+
+    def save(self, manifest):
+        validate_manifest(manifest)
+        revision = hashlib.sha256(canonical(manifest)).hexdigest()
+        pack = safe_id(manifest["packId"])
+        path = self.root / "packs" / pack / "revisions" / (revision + ".json")
+        if not path.exists(): atomic_json(path, manifest)
+        atomic_json(self.root / "packs" / pack / "head.json", {"revision": revision})
+        return revision
+
+    def load(self, name, revision=None):
+        name = safe_id(name)
+        if revision is None:
+            head = self.root / "packs" / name / "head.json"
+            if not head.exists(): raise PackError(f"Pack {name!r} is not installed. Capture or install it first.")
+            revision = read_json(head)["revision"]
+        if not re.fullmatch(r"[a-f0-9]{64}", revision): raise PackError("Invalid revision")
+        path = self.root / "packs" / name / "revisions" / (revision + ".json")
+        if not path.exists(): raise PackError(f"Missing revision {name}@{revision}")
+        value = read_json(path)
+        validate_manifest(value)
+        if hashlib.sha256(canonical(value)).hexdigest() != revision: raise PackError("Manifest integrity mismatch")
+        return value, revision
+
+    def active(self):
+        return read_json(self.root / "active.json", {})
+
+    def pending(self):
+        return [p for p in (self.root / "journals").glob("*.json") if read_json(p).get("phase") not in {"complete", "rolled-back"}]
+
+    def export(self, name, path):
+        manifest, revision = self.load(name)
+        target = pathlib.Path(path).expanduser().resolve()
+        if target.exists(): raise PackError(f"Export destination already exists: {target}")
+        target.parent.mkdir(parents=True, exist_ok=True)
+        refs = references(manifest)
+        fd, temp = tempfile.mkstemp(dir=target.parent, prefix=".pack-export-"); os.close(fd)
+        try:
+            with zipfile.ZipFile(temp, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=4) as archive:
+                archive.writestr("manifest.json", canonical(manifest))
+                for key, ref in sorted(refs.items()): archive.write(self.object(ref), "objects/" + key)
+            os.chmod(temp, 0o600)
+            with open(temp,'rb') as stream: os.fsync(stream.fileno())
+            os.link(temp,target);os.unlink(temp);sync_directory(target.parent)
+        finally:
+            if os.path.exists(temp): os.unlink(temp)
+        return {"pack": name, "revision": revision, "bundle": str(target), "objects": len(refs)}
+
+    def install(self, path, publish=True):
+        path = pathlib.Path(path).expanduser().resolve()
+        with zipfile.ZipFile(path) as archive:
+            names = archive.namelist()
+            if len(names) != len(set(names)) or "manifest.json" not in names:
+                raise PackError("Invalid or duplicate bundle entries")
+            info = archive.getinfo("manifest.json")
+            if info.file_size > 32 * 1024 * 1024: raise PackError("Bundle manifest exceeds 32 MiB")
+            manifest = json.loads(archive.read("manifest.json")); validate_manifest(manifest)
+            refs = references(manifest)
+            allowed = {"manifest.json"} | {"objects/" + key for key in refs}
+            if set(names) != allowed: raise PackError("Bundle contains missing, unexpected or unsafe paths")
+            for key, ref in refs.items():
+                info = archive.getinfo("objects/" + key)
+                if info.file_size != ref["bytes"] or (info.external_attr >> 16) & 0o170000 == 0o120000:
+                    raise PackError("Invalid bundle object size/type")
+                fd, temp = tempfile.mkstemp(dir=self.root / "objects", prefix=".install-")
+                try:
+                    h = hashlib.sha256(); total = 0
+                    with archive.open(info) as source, os.fdopen(fd, "wb") as dest:
+                        while chunk := source.read(1024 * 1024):
+                            total += len(chunk)
+                            if total > ref["bytes"]: raise PackError("Oversized bundle object")
+                            h.update(chunk); dest.write(chunk)
+                        dest.flush(); os.fsync(dest.fileno())
+                    if h.hexdigest() != key or total != ref["bytes"]: raise PackError("Bundle object checksum mismatch")
+                    os.chmod(temp, 0o600)
+                    target = self.root / "objects" / key
+                    if target.exists(): self.object(ref)
+                    else: os.replace(temp, target);sync_directory(target.parent)
+                finally:
+                    if os.path.exists(temp): os.unlink(temp)
+            revision = self.save(manifest) if publish else hashlib.sha256(canonical(manifest)).hexdigest()
+        return manifest, revision
+
+def references(value):
+    result = {}
+    def walk(v):
+        if isinstance(v, dict):
+            if "sha256" in v and "bytes" in v:
+                key = v["sha256"]
+                if key in result and result[key] != v: raise PackError("Conflicting object references")
+                result[key] = v
+            else:
+                for x in v.values(): walk(x)
+        elif isinstance(v, list):
+            for x in v: walk(x)
+    walk(value)
+    return result
+
+def validate_manifest(value):
+    if value.get("format") not in {"topolo-agent-pack", "codex-pack"} or value.get("schemaVersion") != 1:
+        raise PackError("Unsupported pack format/schema")
+    safe_id(value["packId"])
+    keys = set()
+    for agent in value["agents"]:
+        for field in ["pack", "set", "id", "threadId"]: safe_id(agent[field])
+        key = (agent["pack"], agent["set"], agent["id"])
+        if key in keys: raise PackError(f"Duplicate agent identity: {key}")
+        keys.add(key)
+        if agent["threadId"] not in value["threads"]: raise PackError("Agent history record missing")
+    for tid, thread in value["threads"].items():
+        safe_id(tid)
+        if thread.get("historyBase") and thread["historyBase"] not in value["threads"]:
+            raise PackError(f"Missing inherited history dependency for {tid}")
+    for ref in references(value).values():
+        if not isinstance(ref["bytes"], int) or ref["bytes"] < 0 or not re.fullmatch(r"[a-f0-9]{64}", ref["sha256"]):
+            raise PackError("Invalid content reference")
+
+def select(manifest, sets=None, agents=None):
+    candidates = manifest["agents"]
+    if sets:
+        known = {a["set"] for a in candidates}
+        for name in sets:
+            if name not in known: raise PackError(f"Unknown set {name!r}; available: {', '.join(sorted(known))}")
+        candidates = [a for a in candidates if a["set"] in sets]
+    if agents:
+        chosen = []
+        for name in agents:
+            matches = [a for a in candidates if name in {a["id"], '/'.join([a['pack'], a['set'], a['id']]), *a.get('aliases', [])}]
+            if len(matches) != 1: raise PackError(f"Agent selector {name!r} resolved to {len(matches)} agents; use --set to disambiguate.")
+            if matches[0] not in chosen: chosen.append(matches[0])
+        candidates = chosen
+    if not candidates: raise PackError("Selection contains no agents")
+    return candidates
+
+def component_key(agent):
+    return '/'.join([agent['pack'], agent['set'], agent['id']])