RFC-0032: ACP Slash Commands Protocol Compliance

docs/features/skill-commands.md

@@ -37,19 +37,25 @@ Detailed instructions for the agent...
 ## Protocol-Specific Usage
 
 ### ACP Protocol
-Skills appear as AvailableCommand in AgentCapabilities:
+Skills appear as `AvailableCommand` via the `session/update` notification with `available_commands_update` after session creation:
 ```json
 {
-  "slash_commands": [
-    {
-      "name": "my-skill",
-      "description": "A description...",
-      "input": {"hint": "Arguments for skill"}
-    }
-  ]
+  "sessionId": "sess_abc123",
+  "update": {
+    "sessionUpdate": "available_commands_update",
+    "availableCommands": [
+      {
+        "name": "my-skill",
+        "description": "A description...",
+        "input": {"hint": "Arguments for skill"}
+      }
+    ]
+  }
 }
 ```
 
+> **Note**: Per the ACP specification, available commands are declared via `session/update` after session creation, not in the `initialize` response.
+
 ### AG-UI Protocol
 Skills appear as Tools with `skill__` prefix:
 ```json

src/acp/schema/agent_responses.py

@@ -19,7 +19,6 @@
 
 if TYPE_CHECKING:
     from acp.schema import ModelInfo, SessionMode
-    from acp.schema.slash_commands import AvailableCommand
 
 
 StopReason = Literal[
@@ -298,9 +297,8 @@ def create(
         resume_session: bool = False,
         stop_session: bool = False,
         auth_methods: Sequence[AuthMethod] | None = None,
-        slash_commands: Sequence[AvailableCommand] | None = None,
     ) -> Self:
-        """Create an instance of AgentCapabilities.
+        """Create an instance of InitializeResponse.
 
         Args:
             name: The name of the agent.
@@ -317,7 +315,6 @@ def create(
             resume_session: Whether the agent supports `session/resume` (unstable).
             stop_session: Whether the agent supports `session/stop` (unstable).
             auth_methods: The authentication methods supported by the agent.
-            slash_commands: Available slash commands exposed by the agent.
         """
         caps = AgentCapabilities.create(
             load_session=load_session,
@@ -329,7 +326,6 @@ def create(
             list_sessions=list_sessions,
             resume_session=resume_session,
             stop_session=stop_session,
-            slash_commands=list(slash_commands) if slash_commands else None,
         )
         return cls(
             agent_info=Implementation(name=name, title=title, version=version),

src/acp/schema/capabilities.py

@@ -7,7 +7,6 @@
 from pydantic import Field, field_validator
 
 from acp.schema.base import AnnotatedObject
-from acp.schema.slash_commands import AvailableCommand  # noqa: TC001
 
 
 class FileSystemCapability(AnnotatedObject):
@@ -270,13 +269,6 @@ class AgentCapabilities(AnnotatedObject):
     session_capabilities: SessionCapabilities | None = None
     """Session capabilities supported by the agent."""
 
-    slash_commands: list[AvailableCommand] = Field(default_factory=list)
-    """Available slash commands that can be invoked by the client.
-
-    These commands are exposed by the agent for direct invocation
-    via slash command interfaces. Empty list means no commands available.
-    """
-
     @classmethod
     def create(
         cls,
@@ -289,7 +281,6 @@ def create(
         list_sessions: bool = False,
         resume_session: bool = False,
         stop_session: bool = False,
-        slash_commands: list[AvailableCommand] | None = None,
     ) -> Self:
         """Create an instance of AgentCapabilities.
 
@@ -303,7 +294,6 @@ def create(
             list_sessions: Whether the agent supports `session/list` (unstable).
             resume_session: Whether the agent supports `session/resume` (unstable).
             stop_session: Whether the agent supports `session/stop` (unstable).
-            slash_commands: Available slash commands exposed by the agent.
         """
         session_caps = SessionCapabilities(
             list=SessionListCapabilities() if list_sessions else None,
@@ -319,5 +309,4 @@ def create(
                 image=image_prompts,
             ),
             session_capabilities=session_caps,
-            slash_commands=slash_commands or [],
         )

src/agentpool_server/acp_server/acp_agent.py

@@ -307,7 +307,6 @@ async def initialize(self, params: InitializeRequest) -> InitializeResponse:
         self.client_info = params.client_info
         logger.info("Client info", request=params.model_dump_json())
         self._initialized = True
-        skill_commands = self.get_skill_commands()
         return InitializeResponse.create(
             protocol_version=version,
             name="agentpool",
@@ -322,7 +321,6 @@ async def initialize(self, params: InitializeRequest) -> InitializeResponse:
             audio_prompts=True,
             embedded_context_prompts=True,
             image_prompts=True,
-            slash_commands=skill_commands,
         )
 
     async def new_session(self, params: NewSessionRequest) -> NewSessionResponse:

src/agentpool_server/acp_server/session.py

@@ -34,6 +34,7 @@
 )
 from agentpool_server.acp_server.event_converter import ACPEventConverter
 from agentpool_server.acp_server.input_provider import ACPInputProvider
+from agentpool_server.opencode_server.skill_bridge import create_skill_command
 
 
 if TYPE_CHECKING:
@@ -245,8 +246,71 @@ async def permission_callback(
 
             # Subscribe to state change signal for all agents
             agent.state_updated.connect(self._on_state_updated)
+        # Register skill commands from pool's skill_commands registry
+        self._register_skill_commands()
         self.log.info("Created ACP session", current_agent=self.agent.name)
 
+    def _register_skill_commands(self) -> None:
+        """Register skill commands from pool's SkillCommandRegistry to command_store.
+
+        Bridges skill commands into the session's command_store so they are
+        included in available_commands_update notifications per ACP spec.
+        """
+        pool = self.agent_pool
+        skill_registry = getattr(pool, "skill_commands", None)
+        if skill_registry is None:
+            return
+
+        self._skill_command_callback = self._on_skill_command_changed
+        # Skip scheduling updates during initial registration;
+        # the caller of create_session already schedules a consolidated update.
+        self._skill_commands_initializing = True
+        try:
+            skill_registry.on_command_change(self._skill_command_callback)
+        finally:
+            self._skill_commands_initializing = False
+
+        self.log.debug(
+            "Subscribed to skill command changes",
+            skill_count=len(skill_registry.list_items()),
+        )
+
+    def _on_skill_command_changed(self, name: str, command: Any | None) -> None:
+        """Handle skill command add/remove changes from SkillCommandRegistry.
+
+        Args:
+            name: The name of the skill command.
+            command: The SkillCommand if added, None if removed.
+        """
+        if command is None:
+            # Command removed
+            try:
+                self.command_store.unregister_command(name)
+                self.log.debug("Unregistered skill command", skill_name=name)
+            except Exception:
+                self.log.exception("Failed to unregister skill command", skill_name=name)
+        else:
+            # Command added/updated
+            try:
+                from agentpool.skills.command import SkillCommand
+
+                if isinstance(command, SkillCommand):
+                    slashed_cmd = create_skill_command(command)
+                    self.command_store.register_command(slashed_cmd)
+                    self.log.debug("Registered skill command", skill_name=name)
+            except Exception:
+                self.log.exception("Failed to register skill command", skill_name=name)
+
+        # Skip notification during initial registration
+        if getattr(self, "_skill_commands_initializing", False):
+            return
+
+        # Schedule update via TaskManager for proper lifecycle tracking
+        try:
+            self.acp_agent.tasks.create_task(self.send_available_commands_update())
+        except Exception:
+            self.log.exception("Failed to schedule command update")
+
     async def _on_state_updated(
         self, state: ModeInfo | ModelInfo | AvailableCommandsUpdate | ConfigOptionChanged
     ) -> None:
@@ -528,6 +592,15 @@ async def close(self) -> None:
                 if self.get_cwd_context in agent.sys_prompts.prompts:
                     agent.sys_prompts.prompts.remove(self.get_cwd_context)  # pyright: ignore[reportArgumentType]  # ty: ignore[invalid-argument-type]
 
+            # Unregister skill command callback to prevent memory leak
+            if hasattr(self, "_skill_command_callback"):
+                skill_registry = getattr(self.agent_pool, "skill_commands", None)
+                if skill_registry is not None and hasattr(skill_registry, "_command_change_handlers"):
+                    try:
+                        skill_registry._command_change_handlers.remove(self._skill_command_callback)
+                    except ValueError:
+                        pass  # Already removed
+
             # Note: Individual agents are managed by the pool's lifecycle
             # The pool will handle agent cleanup when it's closed
             self.log.info("Closed ACP session")