codex-app-server/cloud/skill_seed.py

"""Seed ChatGPT-Codex-alignment skills into a tenant codex-home.

Mirrors the websearch MCP seeding pattern in cloud/websearch.py,
but for skills, not MCP config:

- Source is cloud/skills/<name>/SKILL.md (the batch-1 skill pack).
- Destination is <codex-home>/.agents/skills/<name>/SKILL.md.
  Why this path: Codex documents personal skills at
  $HOME/.agents/skills and project skills at .agents/skills
  (scanned from the working directory up to the repo root).
  A Docker tenant task must not pollute its task repo/worktree
  (seeding into the worktree would show up in the task diff),
  so the tenant codex-home -- the per-project persistent home
  that is mounted into the container at
  /var/lib/codex-app-server/codex-home -- is the personal-level
  analogue. This is the same channel websearch MCP seeding uses.
- Idempotent and non-destructive by design:
  - a missing destination file is copied;
  - an identical destination file is left alone;
  - a differing destination file is NEVER overwritten (that is
    a tenant-modified skill) -- it is reported in
    ``skills_skipped_differ`` and left alone;
  - a skill directory without SKILL.md is skipped, never invented.
- No config.toml change, no key, no network: skills are plain
  instruction files, and the helper never writes secrets.

Honest boundary (see docs/chatgpt-codex-alignment.md): the
destination path follows the documented personal-skills pattern
mapped onto the tenant home. Whether a given Codex build picks
these skills up in a Docker tenant task still needs a live
verification task (skills/list + an explicit $live-info call),
the same kind of e2e probe websearch MCP got after its seeding
PR. Until that probe passes, do not claim the skills are live
in production tasks -- this helper only guarantees the files
land in the tenant home, idempotently, without clobbering
tenant edits.
"""

import os
import shutil
from pathlib import Path

# cloud/skills/<name>/SKILL.md, next to this module.
SKILLS_DIR = Path(__file__).resolve().parent / "skills"
# Personal-level skills inside a codex-home.
DEST_SUBDIR = Path(".agents") / "skills"


def skill_source_dir(skills_dir=None):
    """Skill pack directory: explicit override or cloud/skills/."""
    if skills_dir is not None:
        return Path(skills_dir)
    return SKILLS_DIR


def list_skills(skills_dir=None):
    """[(name, SKILL.md path)] for every skill in the pack."""
    src = skill_source_dir(skills_dir)
    out = []
    if not src.is_dir():
        return out
    for entry in sorted(src.iterdir()):
        if not entry.is_dir():
            continue
        skill_file = entry / "SKILL.md"
        if skill_file.is_file():
            out.append((entry.name, skill_file))
    return out


def ensure_codex_home_skills(codex_home_dir, skills_dir=None):
    """Copy the skill pack into a tenant codex-home.

    Returns {"dest_dir", "skills_copied", "skills_skipped_differ",
    "skills_skipped_missing"}: copied = names newly written,
    skipped_differ = names whose destination SKILL.md differs
    from the pack (tenant-modified, left alone), skipped_missing
    = skill directories in the pack without a SKILL.md file
    (should not happen; the batch-1 test guards it).
    A missing source directory yields all-empty lists, never
    an exception: skills are optional, a missing pack must not
    block a task the way a missing websearch config would.
    """
    home = Path(codex_home_dir)
    dest_root = home / DEST_SUBDIR
    dest_root.mkdir(parents=True, exist_ok=True)
    copied = []
    skipped_differ = []
    skipped_missing = []
    src = skill_source_dir(skills_dir)
    if not src.is_dir():
        return {"dest_dir": str(dest_root), "skills_copied": copied,
                "skills_skipped_differ": skipped_differ,
                "skills_skipped_missing": skipped_missing}
    # Directories in the pack, including ones without SKILL.md,
    # so a broken pack is reported instead of silently dropped.
    for entry in sorted(src.iterdir()):
        if not entry.is_dir():
            continue
        skill_file = entry / "SKILL.md"
        if not skill_file.is_file():
            skipped_missing.append(entry.name)
            continue
        dest_dir = dest_root / entry.name
        dest_file = dest_dir / "SKILL.md"
        src_bytes = skill_file.read_bytes()
        if dest_file.is_file():
            if dest_file.read_bytes() == src_bytes:
                continue
            skipped_differ.append(entry.name)
            continue
        dest_dir.mkdir(parents=True, exist_ok=True)
        shutil.copyfile(skill_file, dest_file)
        copied.append(entry.name)
    return {"dest_dir": str(dest_root), "skills_copied": copied,
            "skills_skipped_differ": skipped_differ,
            "skills_skipped_missing": skipped_missing}