agents-city 0.3.0-beta.21 → 0.3.0

package/plugin/scripts/workspace.py

@@ -257,6 +257,203 @@ def sincroniza(agente, data):
     return [t for _, t in mounts_en_disco(data, agente.slug)]
 
 
+def como_ficha(agente, motor=None):
+    """One agent in the shape the card writers speak: a plain dict.
+
+    `Agente` is what readers get; this is what writers take. Keeping the two
+    shapes converted in one place is what stops the wizard and the Hall from
+    each inventing their own idea of what an agent looks like on a card.
+    """
+    return {
+        'nombre': agente.nombre,
+        'slug': agente.slug,
+        'clase': agente.clase,
+        'rol': agente.rol,
+        'mounts': list(agente.mounts),
+        'motor': dict(motor or {}),
+        'skills': [],
+    }
+
+
+def claves_de_roster(roster):
+    """Every card key a roster implies: identity, kind, role, mounts, engine.
+
+    The single owner of "what does a city's roster look like on a card". The
+    wizard writes it after asking seven questions and the Hall writes it after
+    one POST; both land here, so neither can drift into writing `kinds.` or
+    forgetting `mounts.` — the class of bug that only appears at the seam.
+    An empty mount list REMOVES the key rather than writing `[]`, because an
+    empty value is how `card.pon_campo` says "back to nothing".
+    """
+    claves = {'agents': '[' + ', '.join(a['nombre'] for a in roster) + ']'}
+    for a in roster:
+        claves[f'kind.{a["slug"]}'] = a['clase']
+        claves[f'role.{a["slug"]}'] = a['rol']
+        claves[f'mounts.{a["slug"]}'] = (
+            '[' + ', '.join(a['mounts']) + ']' if a['mounts'] else ''
+        )
+        for clave, valor in (a.get('motor') or {}).items():
+            claves[clave] = valor
+    return claves
+
+
+# ── skills, the one deliberate write ─────────────────────────────────────────
+#
+# Recognition of skills is read-only everywhere else in this codebase. This is
+# the single exception: the owner explicitly hands over a skill and asks for it
+# to live in one agent's home. Both doors — the wizard's question and the Hall's
+# upload — come through here, so the containment rules are written once. A skill
+# is the Claude runtime's format; other engines ignore the folder entirely.
+
+#: One skill's extraction budget. Whatever bounds the upload (a byte cap, a file
+#: on disk), only these bound what a hostile deflate ratio inflates it to.
+MAX_ENTRADAS_ZIP = 2048
+MAX_EXTRAIDO = 64 * 1024 * 1024
+
+
+def raiz_de_skills(hogar):
+    """The home's own `.claude/skills`, verified to still be inside the home
+    after resolution, or ''.
+
+    A repo can commit `.claude/skills` (or `.claude` itself) as a symlink to
+    anywhere the user can write — the global skills folder included — and both
+    an install and a removal would follow it straight out of the agent's home.
+    """
+    real = os.path.realpath(os.path.join(hogar, '.claude', 'skills'))
+    if real != os.path.join(os.path.realpath(hogar), '.claude', 'skills'):
+        return ''
+    return real
+
+
+def zip_inseguro(entradas):
+    """The shapes a hostile zip uses, refused by name before a byte lands."""
+    if len(entradas) > MAX_ENTRADAS_ZIP:
+        return 'the zip holds too many files for one skill'
+    if sum(info.file_size for info in entradas) > MAX_EXTRAIDO:
+        return 'the zip inflates too large for one skill'
+    for info in entradas:
+        nombre = info.filename
+        if nombre.startswith(('/', '\\')) or '..' in nombre.split('/'):
+            return 'the zip tries to escape its folder'
+        if (info.external_attr >> 16) & 0o170000 == 0o120000:
+            return 'symlinks in a skill are refused'
+    return ''
+
+
+def extrae_zip(archivo, entradas, base, destino):
+    """Write a zip's files under `destino`, containment resolved twice and the
+    decompressed bytes metered as they land — the headers already passed
+    `zip_inseguro`, but a header's declared size is the sender's word."""
+    presupuesto = MAX_EXTRAIDO
+    for info in entradas:
+        relativa = info.filename[len(base):] if info.filename.startswith(base) else ''
+        if not relativa or relativa.endswith('/'):
+            continue
+        ruta = os.path.realpath(os.path.join(destino, relativa))
+        if not ruta.startswith(destino + os.sep) and ruta != destino:
+            return 'the zip tries to escape its folder'
+        os.makedirs(os.path.dirname(ruta), exist_ok=True)
+        with archivo.open(info) as origen, open(ruta, 'wb') as salida:
+            while True:
+                trozo = origen.read(1024 * 64)
+                if not trozo:
+                    break
+                presupuesto -= len(trozo)
+                if presupuesto < 0:
+                    return 'the zip inflates too large for one skill'
+                salida.write(trozo)
+    return ''
+
+
+def _nombre_de_skill_en_zip(entradas, pedido):
+    """The skill's name and its base inside the zip: the single top folder when
+    there is one, else the zip root plus a name the caller supplies."""
+    raices = {e.filename.split('/')[0] for e in entradas if e.filename.strip('/')}
+    con_carpeta = len(raices) == 1 and any(
+        '/' in e.filename or e.filename.endswith('/') for e in entradas
+    )
+    base = (next(iter(raices)) + '/') if con_carpeta else ''
+    crudo = next(iter(raices)) if con_carpeta else str(pedido or '')
+    rutas_dentro = {e.filename[len(base):] for e in entradas if e.filename.startswith(base)}
+    return card.rol_seguro(crudo, defecto=''), base, rutas_dentro
+
+
+def _sitio_para_skill(raiz, etiqueta):
+    """(destination, '') for a free, plainly-named slot under the skills root."""
+    if not etiqueta:
+        return '', 'the skill needs a plain folder name'
+    destino = os.path.join(raiz, etiqueta)
+    if os.path.lexists(destino):
+        return '', f'{etiqueta} already exists there'
+    return destino, ''
+
+
+def _copia_skill(ruta, raiz, nombre):
+    import shutil as _sh
+
+    if not os.path.isfile(os.path.join(ruta, 'SKILL.md')):
+        return '', 'a skill is a folder with a SKILL.md in it'
+    etiqueta = card.rol_seguro(nombre or os.path.basename(ruta.rstrip(os.sep)), defecto='')
+    destino, mal = _sitio_para_skill(raiz, etiqueta)
+    if mal:
+        return '', mal
+    os.makedirs(raiz, exist_ok=True)
+    try:
+        # symlinks=False: a link inside the source would otherwise land in the
+        # agent's home still pointing wherever the copier could reach.
+        _sh.copytree(ruta, destino, symlinks=False, ignore_dangling_symlinks=True)
+    except OSError as e:
+        _sh.rmtree(destino, ignore_errors=True)
+        return '', f'could not install the skill: {e}'
+    return etiqueta, ''
+
+
+def _descomprime_skill(ruta, raiz, nombre):
+    import shutil as _sh
+    import zipfile
+
+    try:
+        archivo = zipfile.ZipFile(ruta)
+        entradas = archivo.infolist()
+    except (OSError, zipfile.BadZipFile):
+        return '', 'that is not a readable folder or zip'
+    mal = zip_inseguro(entradas)
+    if mal:
+        return '', mal
+    etiqueta, base, dentro = _nombre_de_skill_en_zip(entradas, nombre)
+    if 'SKILL.md' not in dentro:
+        return '', 'a skill is a folder with a SKILL.md in it'
+    destino, mal = _sitio_para_skill(raiz, etiqueta)
+    if mal:
+        return '', mal
+    try:
+        os.makedirs(destino)
+        mal = extrae_zip(archivo, entradas, base, destino)
+    except OSError as e:
+        mal = f'could not install the skill: {e}'
+    if mal:
+        _sh.rmtree(destino, ignore_errors=True)
+        return '', mal
+    return etiqueta, ''
+
+
+def instala_skill(data, slug, origen, nombre=None):
+    """Install one skill from a folder or a `.zip` into an agent's own home.
+
+    Returns (skill name, ''), or ('', why). Never raises for a bad input: both
+    callers answer a person, and a traceback is not an answer.
+    """
+    ruta = rutas.canonicaliza(origen)
+    if not os.path.exists(ruta):
+        return '', f'nothing at {ruta}'
+    raiz = raiz_de_skills(crea_workspace(data, slug))
+    if not raiz:
+        return '', "this agent's .claude/skills is a link out of its home"
+    if os.path.isdir(ruta):
+        return _copia_skill(ruta, raiz, nombre)
+    return _descomprime_skill(ruta, raiz, nombre)
+
+
 # ── CLI ──────────────────────────────────────────────────────────────────────