acumen 0.0.1.dev0__py3-none-any.whl

acumen/ship.py

@@ -0,0 +1,298 @@
+"""The shipping agent: make a benchmarked skill installable *into* the target package.
+
+Once a maintainer has benchmarked a skill and knows which version is best, ``acumen ship
+--skill vN`` packages that version into the target so the package gains a ``<dist>-install-skills``
+console script — one command drops the skill into the skills directory of whichever agentic
+framework the user names (``--agent {claude,codex,agents,claude-science}`` or an explicit
+``--dest``) for the package's users. For a GitHub URL the change arrives as a pull request the
+agent opens itself; for a local path it is written straight into the working tree.
+
+The whole point is **generalization**: the agent reasons about the repo — distribution vs import
+name, src-vs-flat layout, build backend — rather than pattern-matching decoupler's shape. So, like
+draft/improve/taskgen, this is an autonomous agent, not a template stamper. The one thing acumen
+stages for it is a clean copy of the skill content (``SKILL.md`` + ``references/``, with acumen's
+``meta.json`` bookkeeping stripped) to be copied verbatim into the wheel.
+
+**Deliberately NOT isolated.** Unlike every other agent, the shipper runs in the user's
+real environment — real network, real git/``gh`` credentials, real ``uv`` — because it builds,
+installs, pushes, and opens a PR. There is nothing to keep honest here: its output is a PR the
+maintainer reviews (or a working-tree diff), so isolation would only stop it doing its job. The
+correctness gate is therefore not env scrubbing but the **build-verify** the agent performs:
+build the wheel in a fresh venv, install it, run the entry point, confirm ``SKILL.md`` ships from
+the installed location — the only thing that catches a mis-wired backend shipping a wheel with no
+skill data. That gate lives in the agent's own turns; acumen trusts the agent's report.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query
+
+from acumen.config import Config
+from acumen.env import API_AUTH_ENV_VARS, SESSION_AUTH_ENV_VAR, AuthMode, Target, claude_cli_dir
+from acumen.logs import LiveLog
+from acumen.procs import label_env, reap
+from acumen.prompts import ship_prompt
+from acumen.skills import Skill, content_files, load_skill
+
+#: A package "already ships an installer" if any console script is named like this.
+_INSTALLER_SUFFIX = "-install-skills"
+
+
+class ShipError(RuntimeError):
+    """Raised when a skill could not be shipped."""
+
+
+@dataclass(frozen=True)
+class ShipResult:
+    """The outcome of a shipping run: what was delivered and what it cost."""
+
+    skill: Skill
+    #: ``"github"`` (a PR was opened) or ``"local"`` (the working tree was edited).
+    mode: str
+    #: The agent's final message — for a GitHub target it carries the PR URL.
+    summary: str
+    cost_usd: float
+    turns: int
+    #: Live log paths for this run, when a :class:`LiveLog` was attached.
+    log_jsonl: Path | None = None
+    log_html: Path | None = None
+
+
+def _script_tables(pyproject: dict) -> list[dict]:
+    """Return every table that can declare console scripts across build backends."""
+    tables: list[dict] = []
+    scripts = pyproject.get("project", {}).get("scripts")
+    if isinstance(scripts, dict):
+        tables.append(scripts)
+    # poetry keeps its scripts under [tool.poetry.scripts]; check it too so a poetry package
+    # that already ships an installer is not clobbered.
+    poetry = pyproject.get("tool", {}).get("poetry", {}).get("scripts")
+    if isinstance(poetry, dict):
+        tables.append(poetry)
+    return tables
+
+
+def installer_exists(src_dir: Path) -> bool:
+    """Whether the target already ships a skills installer.
+
+    True if any declared console script is named ``<something>-install-skills`` (the contract
+    this command creates), or a ``_skills/install.py`` already exists under the source tree.
+    Used as a pre-flight so ``acumen ship`` refuses to clobber an existing installer without
+    ``--force``, before the (costly, real-env) agent runs.
+
+    Parameters
+    ----------
+    src_dir
+        The target package checkout.
+
+    Returns
+    -------
+    Whether an installer is already present.
+    """
+    pyproject = src_dir / "pyproject.toml"
+    if pyproject.is_file():
+        try:
+            data = tomllib.loads(pyproject.read_text())
+        except (OSError, tomllib.TOMLDecodeError):
+            data = {}
+        for table in _script_tables(data):
+            if any(str(name).endswith(_INSTALLER_SUFFIX) for name in table):
+                return True
+    return any(p.name == "install.py" and p.parent.name == "_skills" for p in src_dir.rglob("_skills/install.py"))
+
+
+def _stage_skill_payload(skill: Skill, dest: Path) -> Path:
+    """Copy the skill's content files (no ``meta.json``) into ``dest`` for verbatim shipping.
+
+    :func:`acumen.skills.content_files` already excludes acumen's ``meta.json`` bookkeeping, so
+    what lands in ``dest`` is exactly what should ship in the wheel — ``SKILL.md`` plus any
+    ``references/`` tree, structure preserved.
+    """
+    dest.mkdir(parents=True, exist_ok=True)
+    for path in content_files(skill.directory):
+        rel = path.relative_to(skill.directory)
+        target = dest / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(path, target)
+    return dest
+
+
+def _ship_env(target: Target, auth_mode: AuthMode) -> dict[str, str]:
+    """The environment for the (unisolated) ship agent: the real env, target venv on PATH.
+
+    Unlike the benchmark and meta-agents this is NOT scrubbed — the agent needs real
+    git/``gh`` credentials, network, and ``uv``. The target venv's ``bin`` is prepended so
+    ``python`` resolves to the interpreter with the package installed, matching the other agents;
+    everything else the user has (PATH, HOME, credentials, tokens) is carried through untouched.
+
+    The one exception is the model credential: to bill the chosen ``auth_mode`` deterministically
+    we neutralize the *other* mode's variables — ``"session"`` clears the metered API/cloud keys
+    (the user's real ``~/.claude`` OAuth login then authenticates), ``"api"`` clears the
+    subscription OAuth token (the API key then wins). Everything non-credential is still carried
+    through.
+
+    The cleared variables are set to ``""``, not deleted: the SDK merges this mapping over
+    ``os.environ`` (``{**os.environ, **options.env}``), so a key we merely drop from the dict
+    falls back through from the inherited environment and the run bills the wrong credential. An
+    explicit empty value overrides the inherited one, which the CLI reads as unset.
+    """
+    env = dict(os.environ)
+    drop = API_AUTH_ENV_VARS if auth_mode == "session" else (SESSION_AUTH_ENV_VAR,)
+    for var in drop:
+        env[var] = ""
+    parts = [str(target.bin_dir)]
+    cli_dir = claude_cli_dir()
+    if cli_dir is not None:
+        parts.append(str(cli_dir))
+    existing = env.get("PATH", "")
+    if existing:
+        parts.append(existing)
+    env["PATH"] = os.pathsep.join(parts)
+    return env
+
+
+def _config_dir(env: dict[str, str]) -> Path:
+    """The ``CLAUDE_CONFIG_DIR`` the ship agent's transcript lands under.
+
+    The ship agent is unisolated, so it uses the user's real config dir — ``CLAUDE_CONFIG_DIR``
+    if set, else ``$HOME/.claude`` — never a throwaway.
+    """
+    explicit = env.get("CLAUDE_CONFIG_DIR")
+    if explicit:
+        return Path(explicit)
+    home = env.get("HOME") or str(Path.home())
+    return Path(home) / ".claude"
+
+
+async def ship_skill(
+    *,
+    cfg: Config,
+    target: Target,
+    skills_root: Path,
+    version: str,
+    auth_mode: AuthMode = "session",
+    model: str | None = None,
+    max_turns: int | None = None,
+    max_usd: float | None = None,
+    force: bool = False,
+    log: LiveLog | None = None,
+) -> ShipResult:
+    """Make skill ``version`` installable into the target package.
+
+    Parameters
+    ----------
+    cfg
+        The pass config; supplies ``skill_name`` and ``ship_model``, and ``is_local`` decides
+        whether delivery is a PR (GitHub URL) or a working-tree edit (local path).
+    target
+        The prepared target, supplying the checkout the agent modifies (its ``src_dir``) and the
+        venv interpreter. For a URL this is acumen's clone; for a local path it is the given dir.
+    skills_root
+        The ``skills/`` root; ``version`` is loaded and validated from it.
+    version
+        The skill version to ship, e.g. ``v2``. Required — there is no implicit "latest"/"best".
+    auth_mode
+        Which credential the ship agent authenticates with — ``"session"`` (the Claude
+        subscription) or ``"api"``. Only the model credential is affected; the agent still runs
+        in the user's real environment with real git/``gh``/network access.
+    model
+        Override for the ship model; defaults to ``cfg.ship_model``.
+    max_turns, max_usd
+        Caps for the agent. **Unbounded by default**: shipping builds and installs the
+        package iteratively and runs git/``gh``, so no default budget is imposed.
+    force
+        Proceed even if the target already ships a skills installer (otherwise refused).
+    log
+        A :class:`LiveLog` to stream the agent's messages to and render an HTML log from.
+
+    Returns
+    -------
+    The ship result: the version shipped, the delivery mode, the agent's summary, and cost.
+    """
+    skill = load_skill(skills_root, version, expect_name=cfg.skill_name)
+
+    # Pre-flight, before the costly real-env agent: refuse to clobber an existing installer.
+    if installer_exists(target.src_dir) and not force:
+        raise ShipError(
+            f"{target.pkg_name} already ships a skills installer — pass force=True to ship anyway. "
+            "Shipping over an existing installer risks overwriting a maintainer's own setup."
+        )
+
+    mode = "local" if cfg.is_local else "github"
+
+    holder = Path(tempfile.mkdtemp(prefix="acumen-ship-"))
+    try:
+        skill_src = _stage_skill_payload(skill, holder / "skill")
+
+        prompt = ship_prompt(
+            package=target.pkg_name,
+            skill_name=cfg.skill_name,
+            version=skill.version,
+            checkout=target.src_dir,
+            skill_src=skill_src,
+            mode=mode,
+        )
+        options = ClaudeAgentOptions(
+            # The agent edits the checkout in place, so its cwd IS the checkout.
+            cwd=str(target.src_dir),
+            # Real environment — NOT scrubbed: git/gh creds + network + uv. Marked with the
+            # holder so the teardown below can find whatever the agent leaves running; the
+            # holder path appears nowhere else in this agent's environment.
+            env=label_env(_ship_env(target, auth_mode), holder),
+            model=model or cfg.ship_model,
+            # No default budget cap: only bound the agent if the caller asked.
+            max_turns=max_turns,
+            max_budget_usd=max_usd,
+            # It reads the staged skill payload to copy into the wheel.
+            add_dirs=[str(skill_src)],
+            # No skill discovery: the shipper packages a skill, it does not consume one.
+            setting_sources=[],
+            permission_mode="bypassPermissions",
+            system_prompt={"type": "preset", "preset": "claude_code"},
+        )
+
+        result: ResultMessage | None = None
+        agent_error: Exception | None = None
+        try:
+            async for message in query(prompt=prompt, options=options):
+                if log is not None:
+                    log.append(message)
+                if isinstance(message, ResultMessage):
+                    result = message
+        except Exception as err:  # noqa: BLE001 - a failed ship is an error to report, re-raised below
+            agent_error = err
+        finally:
+            # The ship agent is unisolated, so its transcript lands under the user's real config
+            # dir (not a throwaway). Render the HTML log in a finally so an aborted run (the SDK
+            # raises on a cap breach, after yielding the result) is still inspectable.
+            if log is not None:
+                log.finalize(config_dir=_config_dir(options.env), work_dir=target.src_dir, result=result)
+
+        if agent_error is not None:
+            raise ShipError(f"the shipping agent failed: {type(agent_error).__name__}: {agent_error}") from agent_error
+        if result is None:
+            raise ShipError("the shipping agent produced no result message")
+        if result.is_error:
+            raise ShipError(f"the shipping agent errored: {result.subtype} {result.errors or ''}".strip())
+
+        return ShipResult(
+            skill=skill,
+            mode=mode,
+            summary=result.result or "",
+            cost_usd=result.total_cost_usd or 0.0,
+            turns=result.num_turns,
+            log_jsonl=log.jsonl_path if log is not None else None,
+            log_html=log.html_path if log is not None and log.html_rendered else None,
+        )
+    finally:
+        # Kill anything the agent left running before removing the directory it runs in.
+        # ship's agent works in the target checkout, but its env still points at the holder.
+        reap(holder)
+        shutil.rmtree(holder, ignore_errors=True)

acumen/skills.py

@@ -0,0 +1,298 @@
+"""Skill directories: loading, validation, and a stable content hash.
+
+A skill is a directory — ``SKILL.md`` plus an optional ``references/`` tree — and
+versions are immutable: ``improve`` writes ``skills/v{n+1}/``, never mutates ``v{n}``.
+
+``meta.json`` is acumen's own bookkeeping (version, parent, rationale, hash), not part of
+the skill. It is therefore excluded from :func:`skill_hash` — it *contains* the hash, so
+including it would be circular — and excluded from what gets copied to an agent, which
+has no business reading the rationale for its own skill.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+SKILL_FILE = "SKILL.md"
+META_FILE = "meta.json"
+REFERENCES_DIR = "references"
+
+#: Files that are acumen bookkeeping rather than skill content.
+_NOT_CONTENT = {META_FILE}
+
+_VERSION_RE = re.compile(r"^v(\d+)$")
+_FRONTMATTER_RE = re.compile(r"\A---\r?\n(?P<body>.*?)\r?\n---\s*\r?\n?", re.DOTALL)
+
+
+class SkillError(ValueError):
+    """Raised when a skill directory is missing, malformed, or inconsistent."""
+
+
+@dataclass(frozen=True)
+class SkillMeta:
+    """Provenance for one skill version, as stored in ``meta.json``."""
+
+    version: int
+    parent: str | None
+    rationale: str
+    hash: str
+    #: Maintainer ``--feedback`` that shaped this version, or ``None`` if none was given.
+    feedback: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the ``meta.json`` payload.
+
+        ``feedback`` is omitted when absent, so a version drafted/improved without ``--feedback``
+        writes the same ``meta.json`` it did without the field.
+        """
+        payload: dict[str, Any] = {
+            "version": self.version,
+            "parent": self.parent,
+            "rationale": self.rationale,
+            "hash": self.hash,
+        }
+        if self.feedback:
+            payload["feedback"] = self.feedback
+        return payload
+
+
+@dataclass(frozen=True)
+class Skill:
+    """A loaded, validated skill version."""
+
+    version: str
+    directory: Path
+    name: str
+    description: str
+    hash: str
+
+    @property
+    def number(self) -> int:
+        """The numeric version, e.g. ``1`` for ``"v1"``."""
+        return version_number(self.version)
+
+
+def version_name(number: int) -> str:
+    """Return the directory name for a numeric version, e.g. ``1`` -> ``"v1"``."""
+    if number < 1:
+        raise SkillError(f"skill version must be >= 1, got {number}")
+    return f"v{number}"
+
+
+def version_number(version: str) -> int:
+    """Parse a version directory name, e.g. ``"v1"`` -> ``1``."""
+    match = _VERSION_RE.match(version)
+    if not match:
+        raise SkillError(f"skill version must look like 'v1', got {version!r}")
+    number = int(match.group(1))
+    if number < 1:
+        raise SkillError(f"skill version must be >= 1, got {version!r}")
+    return number
+
+
+def skill_dir(skills_root: Path, version: str | int) -> Path:
+    """Return the directory holding a skill version."""
+    name = version_name(version) if isinstance(version, int) else version
+    version_number(name)  # validate
+    return skills_root / name
+
+
+def content_files(directory: Path) -> list[Path]:
+    """Return the skill's content files, sorted, excluding acumen bookkeeping.
+
+    Sorting by POSIX-relative path keeps the order stable across filesystems, which is
+    what makes :func:`skill_hash` reproducible.
+    """
+    files = [
+        path
+        for path in directory.rglob("*")
+        if path.is_file() and not (path.parent == directory and path.name in _NOT_CONTENT)
+    ]
+    return sorted(files, key=lambda p: p.relative_to(directory).as_posix())
+
+
+def skill_content(directory: Path) -> dict[str, str]:
+    """Return the skill's text content as ``{posix-relpath: text}``, excluding bookkeeping.
+
+    Used by the report to diff one version against its parent. Files that do not decode as
+    UTF-8 (there should be none in a skill) are represented by a short placeholder so a diff
+    still lists them without choking on bytes.
+
+    Returns
+    -------
+    A mapping from each content file's POSIX-relative path to its decoded text.
+    """
+    content: dict[str, str] = {}
+    for path in content_files(directory):
+        rel = path.relative_to(directory).as_posix()
+        try:
+            content[rel] = path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            content[rel] = "<binary file>\n"
+    return content
+
+
+def skill_hash(directory: Path) -> str:
+    """Hash a skill directory's content — the value recorded in every ``result.json``.
+
+    Both the relative path and the bytes of each file are folded in, with lengths, so
+    that renaming a file or moving text between files changes the hash. Byte content is
+    used rather than text, so a line-ending change is a real change.
+
+    Returns
+    -------
+    ``"sha256:<hex>"``.
+    """
+    if not directory.is_dir():
+        raise SkillError(f"skill directory does not exist: {directory}")
+    digest = hashlib.sha256()
+    for path in content_files(directory):
+        rel = path.relative_to(directory).as_posix().encode()
+        data = path.read_bytes()
+        # Length-prefix both parts so no concatenation of names and bodies can collide.
+        digest.update(f"{len(rel)}:".encode())
+        digest.update(rel)
+        digest.update(f"{len(data)}:".encode())
+        digest.update(data)
+    return f"sha256:{digest.hexdigest()}"
+
+
+def parse_frontmatter(text: str) -> dict[str, Any]:
+    """Parse the YAML frontmatter of a ``SKILL.md``.
+
+    Returns
+    -------
+    The frontmatter mapping; empty if the file has none.
+    """
+    match = _FRONTMATTER_RE.match(text)
+    if not match:
+        return {}
+    try:
+        data = yaml.safe_load(match.group("body"))
+    except yaml.YAMLError as err:
+        raise SkillError(f"SKILL.md frontmatter is not valid YAML: {err}") from err
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise SkillError(f"SKILL.md frontmatter must be a mapping, got {type(data).__name__}")
+    return data
+
+
+def load_skill(skills_root: Path, version: str | int, *, expect_name: str | None = None) -> Skill:
+    """Load and validate one skill version.
+
+    Parameters
+    ----------
+    skills_root
+        The ``skills/`` root directory.
+    version
+        ``"v1"`` or ``1``.
+    expect_name
+        If given, the skill's frontmatter ``name`` must match it — this is
+        ``config.skill_name``, and a mismatch means the skill would be injected under a
+        directory name the agent's own frontmatter disagrees with.
+
+    Returns
+    -------
+    The loaded skill, with its content hash computed.
+    """
+    directory = skill_dir(skills_root, version)
+    if not directory.is_dir():
+        raise SkillError(f"no such skill version: {directory}")
+    skill_md = directory / SKILL_FILE
+    if not skill_md.is_file():
+        raise SkillError(f"{directory} has no {SKILL_FILE} — a skill is a directory containing one")
+    try:
+        text = skill_md.read_text()
+    except OSError as err:
+        raise SkillError(f"cannot read {skill_md}: {err}") from err
+
+    front = parse_frontmatter(text)
+    name = front.get("name")
+    description = front.get("description")
+    if not isinstance(name, str) or not name.strip():
+        raise SkillError(f"{skill_md} frontmatter is missing a non-empty 'name'")
+    if not isinstance(description, str) or not description.strip():
+        raise SkillError(
+            f"{skill_md} frontmatter is missing a non-empty 'description' — "
+            "the description is how the agent decides whether to load the skill at all"
+        )
+    if expect_name is not None and name.strip() != expect_name:
+        raise SkillError(
+            f"{skill_md} declares name {name.strip()!r} but config.skill_name is {expect_name!r} — "
+            "they must match, or the skill is injected under a name its own frontmatter disagrees with"
+        )
+
+    return Skill(
+        version=directory.name,
+        directory=directory,
+        name=name.strip(),
+        description=description.strip(),
+        hash=skill_hash(directory),
+    )
+
+
+def available_versions(skills_root: Path) -> list[str]:
+    """Return the skill versions present, in numeric order."""
+    if not skills_root.is_dir():
+        return []
+    found = [p.name for p in skills_root.iterdir() if p.is_dir() and _VERSION_RE.match(p.name)]
+    return sorted(found, key=version_number)
+
+
+def latest_version(skills_root: Path) -> str | None:
+    """Return the highest skill version present, or ``None`` if there are none."""
+    versions = available_versions(skills_root)
+    return versions[-1] if versions else None
+
+
+def next_version(skills_root: Path) -> str:
+    """Return the version a new skill should be written as."""
+    latest = latest_version(skills_root)
+    return version_name(version_number(latest) + 1 if latest else 1)
+
+
+def read_meta(directory: Path) -> SkillMeta | None:
+    """Read a skill version's ``meta.json``, or ``None`` if it has none."""
+    path = directory / META_FILE
+    if not path.is_file():
+        return None
+    try:
+        raw = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError) as err:
+        raise SkillError(f"cannot read {path}: {err}") from err
+    feedback = raw.get("feedback")
+    return SkillMeta(
+        version=int(raw.get("version", 0)),
+        parent=raw.get("parent"),
+        rationale=str(raw.get("rationale", "")),
+        hash=str(raw.get("hash", "")),
+        feedback=str(feedback) if feedback else None,
+    )
+
+
+def write_meta(directory: Path, *, parent: str | None, rationale: str, feedback: str | None = None) -> SkillMeta:
+    """Write ``meta.json`` for a skill version, hashing its content as it stands.
+
+    Call this only once the skill's content files are final — the hash is computed here.
+
+    ``feedback`` records the maintainer ``--feedback`` that shaped this version, for the
+    report's skill-versions provenance; it is omitted from ``meta.json`` when empty.
+    """
+    text = (feedback or "").strip()
+    meta = SkillMeta(
+        version=version_number(directory.name),
+        parent=parent,
+        rationale=rationale.strip(),
+        hash=skill_hash(directory),
+        feedback=text or None,
+    )
+    (directory / META_FILE).write_text(json.dumps(meta.to_dict(), indent=2) + "\n")
+    return meta