agent-toolkit-cli 1.11.0__py3-none-win_amd64.whl

agent_toolkit/compiler/targets/codex.py

@@ -0,0 +1,261 @@
+"""
+OpenAI Codex target adapter.
+
+OpenAI Codex launched a plugin marketplace in March 2026. As of the research
+date (2026-08-04) it is in early experimental status — self-serve marketplace
+submission is "coming soon" and the plugin API surface is still evolving.
+
+**IMPORTANT**: This adapter is labeled ``maturity = "experimental"`` because:
+  1. The Codex plugin API may change without notice.
+  2. Marketplace submission requires explicit authorization from OpenAI.
+  3. Hooks and MCP integration are unknown-blocked (not confirmed by official docs).
+
+Generated artifacts:
+  .codex-plugin/plugin.json    — manifest (different directory from .claude-plugin/)
+  skills/<name>/SKILL.md       — on-demand procedures
+  agents/<name>/AGENT.md       — agent personas
+
+NOT generated:
+  Hooks     — unknown-blocked; not confirmed in official Codex plugin docs.
+  MCP       — unknown-blocked; not confirmed in official Codex plugin docs.
+
+Marketplace note:
+  Codex artifacts MUST NOT be submitted to the Codex marketplace without
+  explicit authorization from OpenAI. The marketplace is gated as of 2026-08-04.
+  Use this adapter to generate the plugin structure for local development only.
+
+Path distinction from Claude Code / Cursor:
+  Claude Code: .claude-plugin/plugin.json
+  Cursor:      .cursor-plugin/plugin.json
+  Codex:       .codex-plugin/plugin.json   ← this adapter
+
+Research: docs/research/platform-capability-matrix.md (2026-08-04)
+Marketplace: https://marketplace.openai.com/codex (gated, submission "coming soon")
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from agent_toolkit.compiler.model import (
+    Agent,
+    CanonicalGraph,
+    CompilationResult,
+    Product,
+    Skill,
+)
+from agent_toolkit.compiler.targets.base import TargetAdapter, private_network_leak_errors
+
+# Settings that must never appear in a publicly distributed Codex plugin.
+# These bypass safety mechanisms and are forbidden in any marketplace submission.
+_FORBIDDEN_CODEX_SETTINGS = {
+    "skipDangerousModePermissionPrompt",
+    "autoAcceptPermissions",
+    "disablePermissionPrompts",
+    "allowUnsafeCode",
+}
+
+
+class CodexAdapter(TargetAdapter):
+    """Compiles agent-toolkit products into OpenAI Codex plugin bundles.
+
+    EXPERIMENTAL: The Codex plugin API launched in March 2026 and is still
+    evolving. Self-serve marketplace submission is "coming soon" as of
+    2026-08-04. Do NOT submit generated artifacts to the marketplace without
+    explicit OpenAI authorization.
+
+    The generated bundle structure mirrors the Codex plugin format:
+      .codex-plugin/plugin.json   — manifest
+      skills/<name>/SKILL.md      — on-demand skills
+      agents/<name>/AGENT.md      — agent personas
+
+    Capability parity:
+      native (experimental):  plugin manifest, skills, agents
+      unknown-blocked:        hooks (not confirmed in official Codex docs)
+      unknown-blocked:        MCP (not confirmed in official Codex docs)
+      unsupported:            lifecycle hooks, MCP integration
+
+    Maturity: experimental — API may change without notice.
+    """
+
+    target_id = "codex"
+    package_type = "plugin"
+    maturity = "experimental"  # MUST remain "experimental" — marketplace is gated
+
+    def compile(self, graph: CanonicalGraph, product: Product) -> CompilationResult:
+        result = CompilationResult(target=self.target_id, product=product.id)
+        out_dir = self.output_root / product.id
+
+        # 1. Emit .codex-plugin/plugin.json (NOT .claude-plugin/ — different path)
+        plugin_json = self._build_plugin_json(product)
+        self._write_file(
+            out_dir / ".codex-plugin" / "plugin.json",
+            json.dumps(plugin_json, indent=2) + "\n",
+            result,
+        )
+        result.emitted.append("plugin-manifest")
+
+        # 2. Emit skills to skills/<name>/SKILL.md
+        for skill_id in product.included_skills:
+            skill = graph.skills.get(skill_id)
+            if skill is None:
+                result.warnings.append(f"Skill '{skill_id}' not found — skipping")
+                result.omitted.append(f"skill:{skill_id}")
+                continue
+            self._emit_skill(skill, out_dir, result)
+
+        # 3. Emit agents to agents/<name>/AGENT.md
+        for agent_id in product.included_agents:
+            agent = graph.agents.get(agent_id)
+            if agent is None:
+                result.warnings.append(f"Agent '{agent_id}' not found — skipping")
+                result.omitted.append(f"agent:{agent_id}")
+                continue
+            self._emit_agent(agent, out_dir, result)
+
+        # 4. Explicitly document unsupported capabilities.
+        #    Never silently drop a capability — always report.
+        result.unsupported.extend(
+            [
+                "hooks — unknown-blocked: lifecycle hooks not confirmed in official Codex plugin docs",
+                "mcp — unknown-blocked: MCP integration not confirmed in official Codex plugin docs",
+            ]
+        )
+
+        # 5. Add an experimental maturity warning to every compilation result.
+        result.warnings.append(
+            "Codex plugin API is experimental (maturity='experimental'). "
+            "Do NOT submit to Codex marketplace without explicit OpenAI authorization. "
+            "Self-serve submission is 'coming soon' as of 2026-08-04."
+        )
+
+        return result
+
+    # ── manifest ──────────────────────────────────────────────────────────────
+
+    def _build_plugin_json(self, product: Product) -> dict:
+        """Build .codex-plugin/plugin.json manifest.
+
+        The Codex manifest uses the same general shape as Claude Code / Cursor
+        plugin.json but is placed in .codex-plugin/ (not .claude-plugin/).
+
+        Security:
+          - No forbidden settings (skipDangerousModePermissionPrompt, etc.)
+          - No private hostnames or IPs
+          - maturity field is always set to "experimental"
+        """
+        try:
+            from agent_toolkit import __version__
+
+            version = __version__
+        except ImportError:
+            version = "1.0.0"
+
+        manifest = {
+            "name": product.id,
+            "version": version,
+            "description": product.description,
+            "maturity": self.maturity,  # always "experimental" — accurately labels this plugin
+            "author": {
+                "name": "ulises-jeremias",
+                "email": "ulisescf.24@gmail.com",
+            },
+            "homepage": "https://github.com/ulises-jeremias/agent-toolkit",
+            "repository": "https://github.com/ulises-jeremias/agent-toolkit",
+            "license": "MIT",
+            "keywords": [
+                "agent-toolkit",
+                product.id.replace("agent-toolkit-", ""),
+                "codex",
+                "skills",
+                "agents",
+            ],
+        }
+
+        # Validate — raise loudly if forbidden settings sneak in
+        errors = self.validate_plugin_json(manifest)
+        # In practice this should never trigger since we build the dict above,
+        # but defensive validation is always correct.
+        for err in errors:
+            raise ValueError(f"Generated Codex plugin.json is invalid: {err}")
+
+        return manifest
+
+    @staticmethod
+    def validate_plugin_json(data: dict) -> list[str]:
+        """Return error messages for any forbidden plugin.json fields or values."""
+        errors = []
+        for field in _FORBIDDEN_CODEX_SETTINGS:
+            if field in data:
+                errors.append(
+                    f"Forbidden field '{field}' in .codex-plugin/plugin.json — "
+                    "this setting bypasses safety mechanisms and is prohibited "
+                    "in any Codex marketplace submission"
+                )
+        text = json.dumps(data)
+        errors.extend(private_network_leak_errors(text, context="plugin.json"))
+        return errors
+
+    # ── skills ────────────────────────────────────────────────────────────────
+
+    def _emit_skill(self, skill: Skill, out_dir: Path, result: CompilationResult) -> None:
+        """Copy SKILL.md to skills/<name>/SKILL.md.
+
+        Codex discovers skills at <plugin-root>/skills/<name>/SKILL.md —
+        the same path convention as Claude Code and Cursor.
+        """
+        if not skill.source_path.exists():
+            result.warnings.append(f"Skill source missing: {skill.source_path}")
+            result.omitted.append(f"skill:{skill.id}")
+            return
+
+        dst = out_dir / "skills" / skill.name
+        dst.mkdir(parents=True, exist_ok=True)
+
+        content = skill.source_path.read_text(encoding="utf-8", errors="replace")
+        self._write_file(dst / "SKILL.md", content, result)
+
+        # Progressive disclosure: copy references/
+        self._copy_skill_references(skill, dst, result)
+
+        result.emitted.append(f"skill:{skill.id}")
+
+    # ── agents ────────────────────────────────────────────────────────────────
+
+    def _emit_agent(self, agent: Agent, out_dir: Path, result: CompilationResult) -> None:
+        """Copy AGENT.md to agents/<name>/AGENT.md."""
+        if not agent.source_path.exists():
+            result.warnings.append(f"Agent source missing: {agent.source_path}")
+            result.omitted.append(f"agent:{agent.id}")
+            return
+
+        dst = out_dir / "agents" / agent.name
+        dst.mkdir(parents=True, exist_ok=True)
+
+        content = agent.source_path.read_text(encoding="utf-8", errors="replace")
+        self._write_file(dst / "AGENT.md", content, result)
+        result.emitted.append(f"agent:{agent.id}")
+
+    # ── parity notes ──────────────────────────────────────────────────────────
+
+    @staticmethod
+    def parity_notes() -> str:
+        return (
+            "OpenAI Codex plugin support is EXPERIMENTAL. The marketplace launched "
+            "in March 2026 but self-serve submission is 'coming soon' as of 2026-08-04. "
+            "Generated artifacts MUST NOT be submitted to the marketplace without "
+            "explicit authorization from OpenAI.\n"
+            "\n"
+            "Manifest path: .codex-plugin/plugin.json\n"
+            "  (distinct from .claude-plugin/ and .cursor-plugin/ — same general schema)\n"
+            "\n"
+            "Hooks and MCP are unknown-blocked — neither surface is confirmed by "
+            "official Codex plugin documentation. They are explicitly reported in "
+            "CompilationResult.unsupported rather than silently dropped.\n"
+            "\n"
+            "The ``maturity`` field in plugin.json is always set to 'experimental' "
+            "to accurately represent the current state of the Codex plugin ecosystem. "
+            "This must not be changed to 'stable' until the Codex plugin API is "
+            "officially stable and marketplace submission is open to all publishers."
+        )

agent_toolkit/compiler/targets/copilot.py

@@ -0,0 +1,275 @@
+"""
+GitHub Copilot CLI and Repository target adapter.
+
+GitHub Copilot has TWO distinct distribution surfaces — both generated from
+the same canonical IR but published separately:
+
+1. **Copilot CLI Plugin** — installable via `copilot plugin install`
+   Root-level `plugin.json` (NOT `.copilot-plugin/` — different schema
+   from Claude Code / Cursor).
+   Discovery paths: skills/, agents/, hooks.json
+
+2. **Repository Surface** — files committed to a project repository
+   `.github/copilot-instructions.md`    — global instructions
+   `.github/agents/<name>.agent.md`     — agent personas (different format!)
+   `.github/skills/<name>/SKILL.md`     — on-demand skills
+   `.github/hooks/<name>.json`          — lifecycle hooks (future)
+
+Official docs:
+  https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference
+Research:
+  docs/research/platform-capability-matrix.md (2026-08-04)
+
+Key differences from Claude Code / Cursor:
+- CLI plugin.json is at ROOT level, not in .copilot-plugin/
+- Agent format uses .agent.md extension (not AGENT.md)
+- Each surface (CLI plugin, repository) must be generated independently
+- Hooks require both Bash (.sh) AND PowerShell (.ps1) handlers
+- MCP: unknown-blocked (not confirmed from official docs as of research date)
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from agent_toolkit.compiler.model import (
+    Agent,
+    CanonicalGraph,
+    CompilationResult,
+    Product,
+    Skill,
+)
+from agent_toolkit.compiler.targets.base import TargetAdapter
+
+
+class CopilotCLIAdapter(TargetAdapter):
+    """Generates GitHub Copilot CLI plugin bundle.
+
+    The plugin is installed via:
+      copilot plugin install <name>@<marketplace>
+    or declared in .github/copilot/settings.json.
+
+    Capability parity:
+      native:         skills, agents (.agent.md format), plugin manifest
+      unknown-blocked: MCP (not confirmed from official docs)
+      unsupported:    hooks (handler format unclear; cross-platform requires
+                      both Bash + PowerShell — pending canonical hook model #16)
+    """
+
+    target_id = "copilot-cli"
+    package_type = "plugin"
+    maturity = "stable"
+
+    def compile(self, graph: CanonicalGraph, product: Product) -> CompilationResult:
+        result = CompilationResult(target=self.target_id, product=product.id)
+        out_dir = self.output_root / product.id
+
+        # 1. Root-level plugin.json (different from .claude-plugin/plugin.json)
+        self._write_file(
+            out_dir / "plugin.json",
+            json.dumps(self._build_plugin_json(product), indent=2) + "\n",
+            result,
+        )
+        result.emitted.append("plugin-manifest")
+
+        # 2. Skills
+        for skill_id in product.included_skills:
+            skill = graph.skills.get(skill_id)
+            if skill is None:
+                result.warnings.append(f"Skill '{skill_id}' not found — skipping")
+                result.omitted.append(f"skill:{skill_id}")
+                continue
+            self._emit_skill(skill, out_dir, result)
+
+        # 3. Agents (.agent.md format — distinct from AGENT.md)
+        for agent_id in product.included_agents:
+            agent = graph.agents.get(agent_id)
+            if agent is None:
+                result.warnings.append(f"Agent '{agent_id}' not found — skipping")
+                result.omitted.append(f"agent:{agent_id}")
+                continue
+            self._emit_agent_cli(agent, out_dir, result)
+
+        # 4. Explicitly report what is not yet implemented
+        result.unsupported.extend(
+            [
+                "hooks (cross-platform Bash+PowerShell handlers required — pending #16)",
+                "mcp (unknown-blocked: not confirmed in official Copilot CLI docs)",
+            ]
+        )
+
+        return result
+
+    def _build_plugin_json(self, product: Product) -> dict:
+        try:
+            from agent_toolkit import __version__
+
+            version = __version__
+        except ImportError:
+            version = "1.0.0"
+
+        return {
+            "name": product.id,
+            "version": version,
+            "description": product.description,
+            "author": {
+                "name": "ulises-jeremias",
+                "url": "https://github.com/ulises-jeremias/agent-toolkit",
+            },
+            "repository": "https://github.com/ulises-jeremias/agent-toolkit",
+            "license": "MIT",
+            "skills": "skills/",
+            "agents": "agents/",
+        }
+
+    def _emit_skill(self, skill: Skill, out_dir: Path, result: CompilationResult) -> None:
+        if not skill.source_path.exists():
+            result.warnings.append(f"Skill source missing: {skill.source_path}")
+            result.omitted.append(f"skill:{skill.id}")
+            return
+
+        dst = out_dir / "skills" / skill.name
+        dst.mkdir(parents=True, exist_ok=True)
+        content = skill.source_path.read_text(encoding="utf-8", errors="replace")
+        self._write_file(dst / "SKILL.md", content, result)
+
+        self._copy_skill_references(skill, dst, result)
+
+        result.emitted.append(f"skill:{skill.id}")
+
+    def _emit_agent_cli(self, agent: Agent, out_dir: Path, result: CompilationResult) -> None:
+        """Emit agent in Copilot CLI .agent.md format.
+
+        The Copilot CLI agent format uses <name>.agent.md (not AGENT.md).
+        Content is the same AGENT.md body with frontmatter.
+        """
+        if not agent.source_path.exists():
+            result.warnings.append(f"Agent source missing: {agent.source_path}")
+            result.omitted.append(f"agent:{agent.id}")
+            return
+
+        dst = out_dir / "agents"
+        dst.mkdir(parents=True, exist_ok=True)
+
+        content = agent.source_path.read_text(encoding="utf-8", errors="replace")
+        # Write as <name>.agent.md (Copilot CLI convention)
+        self._write_file(dst / f"{agent.name}.agent.md", content, result)
+        result.emitted.append(f"agent:{agent.id}")
+
+    @staticmethod
+    def parity_notes() -> str:
+        return (
+            "Copilot CLI plugins use root-level plugin.json (not .copilot-plugin/). "
+            "Agents use the .agent.md extension. Hooks and MCP are not generated — "
+            "hooks need cross-platform handlers; MCP is unknown-blocked pending official docs."
+        )
+
+
+class CopilotRepositoryAdapter(TargetAdapter):
+    """Generates GitHub Copilot repository-scoped assets.
+
+    These are committed to a project repository and activate for
+    all Copilot surfaces (IDE, cloud-agent, CLI) within that repo.
+
+    Generated files:
+      .github/copilot-instructions.md     ← global instructions
+      .github/agents/<name>.agent.md      ← agent personas
+      .github/skills/<name>/SKILL.md      ← on-demand skills
+
+    Capability parity:
+      native:      copilot-instructions.md, agents (.agent.md), skills
+      unsupported: hooks, MCP (not confirmed for repository surface)
+    """
+
+    target_id = "copilot-repository"
+    package_type = "repository-customization"
+    maturity = "stable"
+
+    def compile(self, graph: CanonicalGraph, product: Product) -> CompilationResult:
+        result = CompilationResult(target=self.target_id, product=product.id)
+        out_dir = self.output_root / product.id
+
+        # 1. Global instructions from assistant agent body
+        self._emit_instructions(graph, product, out_dir, result)
+
+        # 2. Skills
+        for skill_id in product.included_skills:
+            skill = graph.skills.get(skill_id)
+            if skill is None:
+                result.omitted.append(f"skill:{skill_id}")
+                continue
+            self._emit_skill_repo(skill, out_dir, result)
+
+        # 3. Agents
+        for agent_id in product.included_agents:
+            agent = graph.agents.get(agent_id)
+            if agent is None:
+                result.omitted.append(f"agent:{agent_id}")
+                continue
+            self._emit_agent_repo(agent, out_dir, result)
+
+        result.unsupported.extend(
+            [
+                "hooks (unknown-blocked for repository surface)",
+                "mcp (unknown-blocked for repository surface)",
+            ]
+        )
+        return result
+
+    def _emit_instructions(
+        self, graph: CanonicalGraph, product: Product, out_dir: Path, result: CompilationResult
+    ) -> None:
+        """Generate .github/copilot-instructions.md from assistant agent."""
+        # Build instructions from assistant agent + product description
+        lines = [
+            f"# {product.name}",
+            "",
+            product.description,
+            "",
+            "## Available skills",
+            "",
+        ]
+        for skill_id in product.included_skills:
+            skill = graph.skills.get(skill_id)
+            if skill:
+                lines.append(f"- **{skill.name}**: {skill.description[:80]}")
+        lines.extend(["", "## Available agents", ""])
+        for agent_id in product.included_agents:
+            agent = graph.agents.get(agent_id)
+            if agent:
+                lines.append(f"- **{agent.name}**: {agent.description[:80]}")
+
+        content = "\n".join(lines) + "\n"
+        github_dir = out_dir / ".github"
+        github_dir.mkdir(parents=True, exist_ok=True)
+        self._write_file(github_dir / "copilot-instructions.md", content, result)
+        result.emitted.append("copilot-instructions.md")
+
+    def _emit_skill_repo(self, skill: Skill, out_dir: Path, result: CompilationResult) -> None:
+        if not skill.source_path.exists():
+            result.omitted.append(f"skill:{skill.id}")
+            return
+        dst = out_dir / ".github" / "skills" / skill.name
+        dst.mkdir(parents=True, exist_ok=True)
+        content = skill.source_path.read_text(encoding="utf-8", errors="replace")
+        self._write_file(dst / "SKILL.md", content, result)
+        result.emitted.append(f"skill:{skill.id}")
+
+    def _emit_agent_repo(self, agent: Agent, out_dir: Path, result: CompilationResult) -> None:
+        if not agent.source_path.exists():
+            result.omitted.append(f"agent:{agent.id}")
+            return
+        dst = out_dir / ".github" / "agents"
+        dst.mkdir(parents=True, exist_ok=True)
+        content = agent.source_path.read_text(encoding="utf-8", errors="replace")
+        self._write_file(dst / f"{agent.name}.agent.md", content, result)
+        result.emitted.append(f"agent:{agent.id}")
+
+    @staticmethod
+    def parity_notes() -> str:
+        return (
+            "Repository surface emits .github/copilot-instructions.md, "
+            ".github/agents/*.agent.md, and .github/skills/*/SKILL.md. "
+            "Hooks and MCP are not generated for the repository surface."
+        )