symphony-code 0.0.1__py3-none-any.whl

coding_agent/addons/skills/bundled_skills/verify-before-done/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: verify-before-done
+description: Do not claim a task is done until the check that would catch a regression has run.
+args:
+  - name: check
+    type: string
+    description: Command or observation that proves the change.
+---
+
+Use `check` when it is set. Otherwise pick the smallest command that fails if the change is wrong.
+Run it and quote the result. If you cannot run it, say what is unverified.

coding_agent/addons/skills/frontmatter.py

@@ -0,0 +1,57 @@
+"""Split and validate the YAML front matter at the top of a SKILL.md.
+
+Why: skill files come from user directories and are pasted into the prompt,
+so the YAML is untrusted. It is size-capped, loaded without aliases, and
+reduced to the three keys the catalog reads: name, description, and args.
+"""
+
+from __future__ import annotations
+
+import re
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field
+
+from coding_agent.addons.skills.args import Description, ExtensionArgs
+
+SKILL_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*$")
+_FRONT_MATTER = re.compile(r"\A---\n(.*?)\n---[ \t]*(?:\n|\Z)", re.S)
+_MAX_FRONT_MATTER_BYTES = 4096
+
+
+class _NoAliasLoader(yaml.SafeLoader):
+    """SafeLoader that rejects YAML aliases (``*name``)."""
+
+    def compose_node(self, parent, index):
+        # WHY: aliases expand exponentially ("billion laughs"); 353 bytes of
+        # front matter took 50s at startup. Skills never need them.
+        if self.check_event(yaml.AliasEvent):
+            raise ValueError("YAML aliases are not allowed in front matter")
+        return super().compose_node(parent, index)
+
+
+class _SkillFrontMatter(BaseModel):
+    """The keys the catalog reads; other standard keys such as allowed-tools are ignored."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    name: str = Field(pattern=SKILL_NAME.pattern, max_length=1000)
+    description: Description
+    args: ExtensionArgs = ()
+
+
+def read_front_matter(text: str) -> _SkillFrontMatter:
+    """Validate the leading ``---`` block of a SKILL.md."""
+    match = _FRONT_MATTER.match(text)
+    if match is None:
+        raise ValueError("SKILL.md must start with a closed YAML front matter block")
+    if len(match.group(1).encode()) > _MAX_FRONT_MATTER_BYTES:
+        raise ValueError(f"front matter exceeds the {_MAX_FRONT_MATTER_BYTES} byte limit")
+    try:
+        data = yaml.load(match.group(1), Loader=_NoAliasLoader)
+    except (yaml.YAMLError, RecursionError) as exc:
+        raise ValueError(f"invalid YAML front matter: {exc}") from exc
+    return _SkillFrontMatter.model_validate(data)
+
+
+__all__ = ["SKILL_NAME", "read_front_matter"]

coding_agent/addons/skills/models.py

@@ -0,0 +1,57 @@
+"""Validated metadata for local skills."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from coding_agent.addons.skills.args import ExtensionArg
+
+CATALOG_DESCRIPTION_CHARS = 160
+
+
+@dataclass(frozen=True)
+class Skill:
+    """A discovered skill and its validated front matter."""
+
+    skill_id: str
+    name: str
+    description: str
+    root: Path
+    origin: str
+    args: tuple[ExtensionArg, ...] = ()
+
+    def catalog_line(self) -> str:
+        """One short prompt line: id and description. The body loads via the skill tool."""
+        description = self.description
+        if len(description) > CATALOG_DESCRIPTION_CHARS:
+            description = description[: CATALOG_DESCRIPTION_CHARS - 1].rstrip() + "…"
+        return f"- {self.skill_id}: {description}"
+
+    @property
+    def resources(self) -> tuple[str, ...]:
+        paths: list[str] = []
+        for path in sorted(self.root.rglob("*")):
+            if not path.is_file() or path.is_symlink():
+                continue
+            try:
+                relative = path.relative_to(self.root)
+                path.resolve().relative_to(self.root.resolve())
+            except ValueError:
+                continue
+            if relative.name == "SKILL.md":
+                continue
+            if relative.parts and relative.parts[0] in {"references", "scripts", "assets"}:
+                paths.append(relative.as_posix())
+        return tuple(paths)
+
+
+@dataclass(frozen=True)
+class SkillDiagnostic:
+    """A bounded, user-facing discovery diagnostic."""
+
+    source: str
+    message: str
+
+
+__all__ = ["Skill", "SkillDiagnostic"]

coding_agent/addons/skills/registry.py

@@ -0,0 +1,109 @@
+"""Safe discovery and bounded access to local Markdown skills."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Iterable
+
+from coding_agent.addons.skills.frontmatter import SKILL_NAME, read_front_matter
+from coding_agent.addons.skills.models import Skill, SkillDiagnostic
+
+logger = logging.getLogger(__name__)
+MAX_SKILL_FILE_BYTES = 128_000
+
+
+def bundled_skills_root() -> Path:
+    """Skills shipped in the package, so every install starts with the same habits without copying files."""
+    return Path(__file__).resolve().parent / "bundled_skills"
+
+
+class SkillRegistry:
+    """Discover skills and expose only paths within their skill roots."""
+
+    def __init__(self, skills: Iterable[Skill] = ()) -> None:
+        self._skills = {skill.skill_id: skill for skill in skills}
+
+    @property
+    def skills(self) -> tuple[Skill, ...]:
+        return tuple(sorted(self._skills.values(), key=lambda skill: skill.skill_id))
+
+    def get(self, skill_id: str) -> Skill:
+        try:
+            return self._skills[skill_id]
+        except KeyError as exc:
+            raise ValueError(f"Unknown skill id: {skill_id}") from exc
+
+    def resource_path(self, skill_id: str, relative_path: str) -> Path:
+        skill = self.get(skill_id)
+        candidate = Path(relative_path)
+        if candidate.is_absolute() or not relative_path or "" in candidate.parts:
+            raise ValueError("resource path must be relative")
+        original = skill.root / candidate
+        resolved = original.resolve()
+        if not resolved.is_relative_to(skill.root.resolve()):
+            raise ValueError("resource path escapes the skill")
+        if any(part.is_symlink() for part in _parents_from(skill.root, original)):
+            raise ValueError("symlink skill resources are not supported")
+        if not resolved.is_file():
+            raise ValueError(f"Skill resource not found: {relative_path}")
+        return resolved
+
+    @classmethod
+    def discover(
+        cls,
+        roots: Iterable[tuple[str, Path]],
+        *,
+        max_skills: int = 100,
+    ) -> tuple["SkillRegistry", tuple[SkillDiagnostic, ...]]:
+        """Load every SKILL.md under ``roots``; a broken skill becomes a diagnostic, never a crash."""
+        found: list[Skill] = []
+        diagnostics: list[SkillDiagnostic] = []
+        seen: set[str] = set()
+        for origin, root in roots:
+            root = root.expanduser().resolve()
+            if not root.is_dir():
+                continue
+            candidates = [root] if (root / "SKILL.md").is_file() else sorted(
+                path for path in root.iterdir() if path.is_dir()
+            )
+            for skill_root in candidates:
+                document = skill_root / "SKILL.md"
+                if not document.is_file():
+                    continue
+                try:
+                    skill = _parse_skill(origin, skill_root, document)
+                    if skill.skill_id in seen:
+                        raise ValueError(f"duplicate skill id: {skill.skill_id}")
+                    seen.add(skill.skill_id)
+                    if len(found) >= max_skills:
+                        diagnostics.append(SkillDiagnostic(str(document), "skill limit reached"))
+                        continue
+                    found.append(skill)
+                except (OSError, UnicodeError, ValueError) as exc:
+                    logger.warning("Skipping skill %s: %s", document, exc)
+                    diagnostics.append(SkillDiagnostic(str(document), str(exc)))
+        return cls(found), tuple(diagnostics)
+
+
+def _parents_from(root: Path, path: Path) -> list[Path]:
+    current = root
+    parents: list[Path] = []
+    for part in path.relative_to(root).parts:
+        current = current / part
+        parents.append(current)
+    return parents
+
+
+def _parse_skill(origin: str, root: Path, document: Path) -> Skill:
+    if not SKILL_NAME.fullmatch(root.name):
+        raise ValueError("skill directory name must be one identifier segment")
+    if document.stat().st_size > MAX_SKILL_FILE_BYTES:
+        raise ValueError("SKILL.md exceeds the 128000 byte limit")
+    text = document.read_text(encoding="utf-8").lstrip("\ufeff").replace("\r\n", "\n")
+    meta = read_front_matter(text)
+    return Skill(skill_id=f"{origin}/{meta.name}", name=meta.name, description=meta.description,
+                 root=root, origin=origin, args=meta.args)
+
+
+__all__ = ["MAX_SKILL_FILE_BYTES", "SkillRegistry", "bundled_skills_root"]

coding_agent/addons/skills/tool.py

@@ -0,0 +1,54 @@
+"""Load a skill's instructions on demand instead of carrying them in every prompt."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import Field
+
+from coding_agent.addons.skills.args import render_args
+from coding_agent.addons.skills.registry import MAX_SKILL_FILE_BYTES, SkillRegistry
+from coding_agent.tools.base import ToolArgsModel, WorkspaceTool
+
+
+class SkillArgs(ToolArgsModel):
+    skill_id: str = Field(..., min_length=1, description="Skill id from the catalog, e.g. 'bundled/orient-first'.")
+    resource: str = Field(
+        default="",
+        description="Optional file inside the skill (a path listed under resources). Empty loads SKILL.md.",
+    )
+
+
+class SkillTool(WorkspaceTool):
+    name = "skill"
+    description = (
+        "Load a skill when it applies to the task. The system prompt lists only skill ids and "
+        "one-line descriptions; this returns the full SKILL.md instructions plus the skill's "
+        "resource files. Pass resource to read one of those files."
+    )
+    args_model = SkillArgs
+
+    def __init__(self, workspace: str | Path, *, registry: SkillRegistry) -> None:
+        self.registry = registry
+        super().__init__(workspace, parallel=True)
+
+    def run(self, skill_id: str, resource: str = "") -> str:
+        try:
+            skill = self.registry.get(skill_id)
+            path = self.registry.resource_path(skill_id, resource or "SKILL.md")
+            if path.stat().st_size > MAX_SKILL_FILE_BYTES:
+                return f"error: {resource or 'SKILL.md'} exceeds the {MAX_SKILL_FILE_BYTES} byte limit"
+            text = path.read_text(encoding="utf-8").lstrip("\ufeff")
+        except (OSError, UnicodeError, ValueError) as exc:
+            return f"error: {exc}"
+        if resource:
+            return text
+        header = [f"# skill {skill.skill_id}"]
+        if skill.args:
+            header.append(f"args: {render_args(skill.args)}")
+        if skill.resources:
+            header.append("resources: " + ", ".join(skill.resources))
+        return "\n".join(header) + "\n\n" + text
+
+
+__all__ = ["SkillArgs", "SkillTool"]

coding_agent/addons/voice/__init__.py

@@ -0,0 +1,5 @@
+"""Realtime Grok voice as a harness add-on."""
+
+from coding_agent.addons.voice.addon import VoiceAddon
+
+__all__ = ["VoiceAddon"]

coding_agent/addons/voice/addon.py

@@ -0,0 +1,106 @@
+"""Harness hook that speaks the summary through TTS.
+
+``feed`` keeps nothing: streamed assistant text is not dictated. The realtime
+socket only listens and speaks the short acknowledgement, then closes.
+``after_run`` speaks the spoken-summary section on a TTS socket, which stays
+open until that audio finishes.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from core_harness.addons.addon import Addon
+
+from coding_agent.addons.voice.speak import StreamingSpeaker
+from coding_agent.addons.voice.stream import VoiceStream
+from coding_agent.addons.voice.summary import spoken_summary
+
+
+class VoiceAddon(Addon):
+    """Speak around a run without joining the chat model call."""
+
+    name = "voice"
+
+    def __init__(
+        self,
+        stream: VoiceStream | None = None,
+        *,
+        on_speaking: Any = None,
+        on_transcript: Any = None,
+        on_commit: Any = None,
+    ) -> None:
+        self.stream = stream or VoiceStream(
+            on_speaking=on_speaking, on_transcript=on_transcript, on_commit=on_commit,
+        )
+        self._open = False
+        self._armed = False
+        self._speaker: StreamingSpeaker | None = None
+
+    def arm(self) -> None:
+        """Opt in exactly one microphone-originated run; typed runs stay silent."""
+        self._armed = True
+
+    def fork_for_child(self, parent_harness: Any) -> None:
+        return None
+
+    def attach(self, harness: Any) -> None:
+        del harness
+        return None
+
+    def open(self) -> str:
+        """Start the background stream. Returns an error string, or ``""``.
+
+        A finished utterance closes its own socket, so the next listen starts
+        a new one instead of talking to a dead connection.
+        """
+        if self._open and not getattr(self.stream, "alive", True):
+            self._open = False
+        if not self._open:
+            self.stream.start()
+            self._open = True
+        return self.stream.error
+
+    def close(self, *, timeout: float = 0.0) -> None:
+        """Stop speech and the realtime socket. Waits up to ``timeout``."""
+        self._armed = False
+        speaker = self._speaker
+        self._speaker = None
+        if speaker is not None:
+            speaker.close(timeout=timeout)
+        if self._open:
+            self.stream.close(timeout=timeout)
+        self._open = False
+
+    def feed(self, text: str) -> None:
+        """Keep the latest assistant text. Speech waits for the final answer."""
+        del text
+        return None
+
+    async def before_run(self, **payload: Any) -> None:
+        """Keep the mic quiet while the run goes. Do not speak a fixed line."""
+        del payload
+        if self._armed:
+            self.stream.hold()
+
+    async def after_run(self, **payload: Any) -> None:
+        if not self._armed:
+            return
+        self._armed = False
+        result = payload.get("result")
+        # Only a question that arrived by voice is dictated. The flag lives on
+        # the harness for the run and is copied onto its result.
+        if not bool(getattr(result, "reply_aloud", False)):
+            # A typed turn never speaks. The listen socket, if one is up,
+            # hangs up with the acknowledgement and is not held open here.
+            return
+        text = spoken_summary(str(getattr(result, "output_text", "") or ""))
+        if not text:
+            return
+        # TTS, not another realtime socket. The realtime model speaks an
+        # acknowledgement and then its response.done tears the connection
+        # down, which was cutting this line off before it could be heard.
+        # The TTS socket stays up until audio.done and plays the MP3 itself.
+        speaker = StreamingSpeaker(on_speaking=getattr(self.stream, "_on_speaking", None))
+        speaker.finish(text)
+        self._speaker = speaker

coding_agent/addons/voice/credentials.py

@@ -0,0 +1,42 @@
+"""xAI audio endpoint, TTS voice, and the bearer every voice socket uses.
+
+The TUI's microphone path and the voice add-on both authenticate here, so this
+lives with the add-on and the TUI imports it, never the other way round.
+"""
+
+from __future__ import annotations
+
+import os
+
+# Built-in TTS voice. eve is the API default.
+GROK_TTS_VOICE = "eve"
+
+
+class UnavailableVoice(RuntimeError):
+    """Raised when the microphone or the Grok voice model cannot be reached."""
+
+
+# The Grok CLI chat proxy only serves chat models. ``/chat/completions`` there
+# is a 404, so voice audio goes to the xAI audio endpoint. The bearer is still
+# the same device-login token a ``grok:`` model call uses.
+XAI_AUDIO_BASE_URL = "https://api.x.ai/v1"
+
+
+def grok_voice_credentials() -> tuple[str, dict[str, str]]:
+    """Bearer and extra headers for one voice transcription.
+
+    An ``XAI_API_KEY`` wins, same as model calls. Otherwise the stored xAI
+    device login is reused. The chat-proxy base URL is not used: it has no
+    audio route.
+    """
+    api_key = os.getenv("XAI_API_KEY", "").strip()
+    if api_key:
+        return api_key, {}
+    from core_ai.oauth.runtime import oauth_runtime_for
+
+    runtime = oauth_runtime_for("grok")
+    if runtime is None or not runtime.api_key:
+        raise UnavailableVoice(
+            "Voice mode needs a Grok sign-in. Run /provider and choose xAI, or set XAI_API_KEY."
+        )
+    return runtime.api_key, dict(runtime.extra_headers)

coding_agent/addons/voice/playback.py

@@ -0,0 +1,42 @@
+"""Play MP3 bytes with whichever command-line player the machine has."""
+
+from __future__ import annotations
+
+import os
+
+from coding_agent.addons.voice.credentials import UnavailableVoice
+
+
+def play_mp3(audio: bytes) -> None:
+    """Play MP3 bytes on the default output. No extra audio package required."""
+    if not audio:
+        return
+    import subprocess
+    import tempfile
+
+    with tempfile.NamedTemporaryFile(suffix=".mp3", delete=False) as handle:
+        handle.write(audio)
+        path = handle.name
+    try:
+        player = _mp3_player(path)
+        if player is None:
+            raise UnavailableVoice("No audio player found to speak the reply.")
+        subprocess.run(player, check=False, capture_output=True, timeout=120)
+    finally:
+        try:
+            os.remove(path)
+        except OSError:
+            pass
+
+
+def _mp3_player(path: str) -> list[str] | None:
+    import shutil
+    import sys
+
+    if sys.platform == "darwin" and shutil.which("afplay"):
+        return ["afplay", path]
+    if shutil.which("ffplay"):
+        return ["ffplay", "-nodisp", "-autoexit", "-loglevel", "quiet", path]
+    if shutil.which("mpv"):
+        return ["mpv", "--no-video", "--really-quiet", path]
+    return None