jupyter-ai-acp-client 0.0.1__py3-none-any.whl

jupyter_ai_acp_client/routes.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from jupyter_server.base.handlers import APIHandler
+import tornado
+from pydantic import BaseModel
+from .base_acp_persona import BaseAcpPersona
+
+if TYPE_CHECKING:
+    from jupyter_server_fileid.manager import BaseFileIdManager
+    from jupyter_ai_persona_manager import PersonaManager
+
+class AcpSlashCommand(BaseModel):
+    name: str
+    description: str
+
+class AcpSlashCommandsResponse(BaseModel):
+    commands: list[AcpSlashCommand] = []
+
+class AcpSlashCommandsHandler(APIHandler):
+    @property
+    def file_id_manager(self) -> BaseFileIdManager:
+        manager = self.serverapp.web_app.settings["file_id_manager"]
+        assert manager
+        return manager
+    
+    @tornado.web.authenticated
+    def get(self, persona_mention_name: str = ""):
+        # get chat path
+        chat_path = self.get_argument('chat_path', None)
+        if not chat_path:
+            # raise HTTP error: chat_path is required URL query arg
+            raise tornado.web.HTTPError(400, "chat_path is required as a URL query parameter")
+        
+        # get chat room ID using file ID manager
+        file_id = self.file_id_manager.get_id(chat_path)
+        if not file_id:
+            raise tornado.web.HTTPError(404, f"Chat not found: {chat_path}")
+        room_id = f"text:chat:{file_id}"
+        
+        # get persona manager
+        persona_manager: PersonaManager | None = self.serverapp.web_app.settings.get("jupyter-ai", {}).get("persona-managers", {}).get(room_id, None)
+        if not persona_manager:
+            raise tornado.web.HTTPError(404, f"Chat not initialized: {chat_path}")
+
+        if persona_mention_name:
+            for p in persona_manager.personas.values():
+                if p.as_user().mention_name == persona_mention_name:
+                    persona = p
+                    break
+            if not persona:
+                # raise HTTP error: persona not found
+                raise tornado.web.HTTPError(404, f"Persona not found: @{persona_mention_name}")
+        else:
+            persona = persona_manager.last_mentioned_persona or persona_manager.default_persona
+
+        # Return early with empty response if either:
+        # 1. no default persona, or
+        # 2. default persona is not ACP persona, or
+        # 3. mentioned persona is not ACP persona.
+        if not isinstance(persona, BaseAcpPersona):
+            self.finish(AcpSlashCommandsResponse().model_dump())
+            return
+        
+        # Otherwise get the ACP slash commands from the persona.
+        # Convert slash commands to the response format
+        commands = []
+        for cmd in persona.acp_slash_commands:
+            name = cmd.name if cmd.name.startswith("/") else "/" + cmd.name
+            commands.append(
+                AcpSlashCommand(
+                    name=name,
+                    description=cmd.description
+                )
+            )
+
+        response = AcpSlashCommandsResponse(commands=commands)
+        self.finish(response.model_dump())

jupyter_ai_acp_client/static/claude.svg

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Generated by Pixelmator Pro 3.6.17 -->
+<svg width="1200" height="1200" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
+    <g id="g314">
+        <path id="path147" fill="#d97757" stroke="none" d="M 233.959793 800.214905 L 468.644287 668.536987 L 472.590637 657.100647 L 468.644287 650.738403 L 457.208069 650.738403 L 417.986633 648.322144 L 283.892639 644.69812 L 167.597321 639.865845 L 54.926208 633.825623 L 26.577238 627.785339 L 3.3e-05 592.751709 L 2.73832 575.27533 L 26.577238 559.248352 L 60.724873 562.228149 L 136.187973 567.382629 L 249.422867 575.194763 L 331.570496 580.026978 L 453.261841 592.671082 L 472.590637 592.671082 L 475.328857 584.859009 L 468.724915 580.026978 L 463.570557 575.194763 L 346.389313 495.785217 L 219.543671 411.865906 L 153.100723 363.543762 L 117.181267 339.060425 L 99.060455 316.107361 L 91.248367 266.01355 L 123.865784 230.093994 L 167.677887 233.073853 L 178.872513 236.053772 L 223.248367 270.201477 L 318.040283 343.570496 L 441.825592 434.738342 L 459.946411 449.798706 L 467.194672 444.64447 L 468.080597 441.020203 L 459.946411 427.409485 L 392.617493 305.718323 L 320.778564 181.932983 L 288.80542 130.630859 L 280.348999 99.865845 C 277.369171 87.221436 275.194641 76.590698 275.194641 63.624268 L 312.322174 13.20813 L 332.8591 6.604126 L 382.389313 13.20813 L 403.248352 31.328979 L 434.013519 101.71814 L 483.865753 212.537048 L 561.181274 363.221497 L 583.812134 407.919434 L 595.892639 449.315491 L 600.40271 461.959839 L 608.214783 461.959839 L 608.214783 454.711609 L 614.577271 369.825623 L 626.335632 265.61084 L 637.771851 131.516846 L 641.718201 93.745117 L 660.402832 48.483276 L 697.530334 24.000122 L 726.52356 37.852417 L 750.362549 72 L 747.060486 94.067139 L 732.886047 186.201416 L 705.100708 330.52356 L 686.979919 427.167847 L 697.530334 427.167847 L 709.61084 415.087341 L 758.496704 350.174561 L 840.644348 247.490051 L 876.885925 206.738342 L 919.167847 161.71814 L 946.308838 140.29541 L 997.61084 140.29541 L 1035.38269 196.429626 L 1018.469849 254.416199 L 965.637634 321.422852 L 921.825562 378.201538 L 859.006714 462.765259 L 819.785278 530.41626 L 823.409424 535.812073 L 832.75177 534.92627 L 974.657776 504.724915 L 1051.328979 490.872559 L 1142.818848 475.167786 L 1184.214844 494.496582 L 1188.724854 514.147644 L 1172.456421 554.335693 L 1074.604126 578.496765 L 959.838989 601.449829 L 788.939636 641.879272 L 786.845764 643.409485 L 789.261841 646.389343 L 866.255127 653.637634 L 899.194702 655.409424 L 979.812134 655.409424 L 1129.932861 666.604187 L 1169.154419 692.537109 L 1192.671265 724.268677 L 1188.724854 748.429688 L 1128.322144 779.194641 L 1046.818848 759.865845 L 856.590759 714.604126 L 791.355774 698.335754 L 782.335693 698.335754 L 782.335693 703.731567 L 836.69812 756.885986 L 936.322205 846.845581 L 1061.073975 962.81897 L 1067.436279 991.490112 L 1051.409424 1014.120911 L 1034.496704 1011.704712 L 924.885986 929.234924 L 882.604126 892.107544 L 786.845764 811.48999 L 780.483276 811.48999 L 780.483276 819.946289 L 802.550415 852.241699 L 919.087341 1027.409424 L 925.127625 1081.127686 L 916.671204 1098.604126 L 886.469849 1109.154419 L 853.288696 1103.114136 L 785.073914 1007.355835 L 714.684631 899.516785 L 657.906067 802.872498 L 650.979858 806.81897 L 617.476624 1167.704834 L 601.771851 1186.147705 L 565.530212 1200 L 535.328857 1177.046997 L 519.302124 1139.919556 L 535.328857 1066.550537 L 554.657776 970.792053 L 570.362488 894.68457 L 584.536926 800.134277 L 592.993347 768.724976 L 592.429626 766.630859 L 585.503479 767.516968 L 514.22821 865.369263 L 405.825531 1011.865906 L 320.053711 1103.677979 L 299.516815 1111.812256 L 263.919525 1093.369263 L 267.221497 1060.429688 L 287.114136 1031.114136 L 405.825531 880.107361 L 477.422913 786.52356 L 523.651062 732.483276 L 523.328918 724.671265 L 520.590698 724.671265 L 205.288605 929.395935 L 149.154434 936.644409 L 124.993355 914.01355 L 127.973183 876.885986 L 139.409409 864.80542 L 234.201385 799.570435 L 233.879227 799.8927 Z"/>
+    </g>
+</svg>

jupyter_ai_acp_client/static/test.svg

@@ -0,0 +1,40 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="100" height="100">
+  <!-- Background -->
+  <rect width="100" height="100" rx="12" fill="#4A90D9"/>
+
+  <!-- Antenna -->
+  <line x1="50" y1="8" x2="50" y2="18" stroke="#2D3748" stroke-width="3" stroke-linecap="round"/>
+  <circle cx="50" cy="6" r="4" fill="#F6AD55"/>
+
+  <!-- Robot Head -->
+  <rect x="20" y="22" width="60" height="50" rx="8" fill="#E2E8F0"/>
+  <rect x="20" y="22" width="60" height="50" rx="8" fill="none" stroke="#2D3748" stroke-width="2"/>
+
+  <!-- Eyes -->
+  <rect x="28" y="34" width="16" height="12" rx="3" fill="#2D3748"/>
+  <rect x="56" y="34" width="16" height="12" rx="3" fill="#2D3748"/>
+
+  <!-- Eye glow -->
+  <circle cx="36" cy="40" r="4" fill="#48BB78"/>
+  <circle cx="64" cy="40" r="4" fill="#48BB78"/>
+
+  <!-- Mouth / Speaker grille -->
+  <rect x="35" y="54" width="30" height="10" rx="2" fill="#2D3748"/>
+  <line x1="40" y1="56" x2="40" y2="62" stroke="#E2E8F0" stroke-width="2"/>
+  <line x1="45" y1="56" x2="45" y2="62" stroke="#E2E8F0" stroke-width="2"/>
+  <line x1="50" y1="56" x2="50" y2="62" stroke="#E2E8F0" stroke-width="2"/>
+  <line x1="55" y1="56" x2="55" y2="62" stroke="#E2E8F0" stroke-width="2"/>
+  <line x1="60" y1="56" x2="60" y2="62" stroke="#E2E8F0" stroke-width="2"/>
+
+  <!-- Ears / Side panels -->
+  <rect x="10" y="35" width="8" height="20" rx="2" fill="#CBD5E0" stroke="#2D3748" stroke-width="1.5"/>
+  <rect x="82" y="35" width="8" height="20" rx="2" fill="#CBD5E0" stroke="#2D3748" stroke-width="1.5"/>
+
+  <!-- Body hint -->
+  <rect x="30" y="74" width="40" height="18" rx="4" fill="#E2E8F0" stroke="#2D3748" stroke-width="2"/>
+
+  <!-- Body details -->
+  <circle cx="42" cy="83" r="3" fill="#F6AD55"/>
+  <circle cx="50" cy="83" r="3" fill="#48BB78"/>
+  <circle cx="58" cy="83" r="3" fill="#FC8181"/>
+</svg>

jupyter_ai_acp_client/terminal_manager.py

@@ -0,0 +1,334 @@
+"""Terminal manager for ACP client terminal operations."""
+
+import asyncio
+import os
+import uuid
+from asyncio.subprocess import Process
+from dataclasses import dataclass, field
+from typing import Any
+
+from acp import RequestError
+from acp.schema import (
+    CreateTerminalResponse,
+    EnvVariable,
+    KillTerminalCommandResponse,
+    ReleaseTerminalResponse,
+    TerminalExitStatus,
+    TerminalOutputResponse,
+    WaitForTerminalExitResponse,
+)
+
+
+@dataclass
+class TerminalInfo:
+    """Tracks state for a single terminal instance."""
+
+    process: Process
+    session_id: str
+    output_buffer: bytearray = field(default_factory=bytearray)
+    output_byte_limit: int | None = None
+    truncated: bool = False
+    exit_code: int | None = None
+    exit_signal: str | None = None
+    _output_task: asyncio.Task | None = field(default=None, repr=False)
+
+
+class TerminalManager:
+    """
+    Manages terminal lifecycle for ACP client.
+
+    Handles creation, output capture, waiting, killing, and releasing
+    of terminal processes according to the ACP terminal protocol.
+    """
+
+    def __init__(self, event_loop: asyncio.AbstractEventLoop):
+        """
+        Initialize the terminal manager.
+
+        :param event_loop: The asyncio event loop for creating background tasks.
+        """
+        self._event_loop = event_loop
+        self._terminals: dict[str, TerminalInfo] = {}
+
+    def _validate_terminal(self, terminal_id: str, session_id: str) -> TerminalInfo:
+        """
+        Validate terminal exists and belongs to the session.
+
+        :raises RequestError: If terminal not found or belongs to different session.
+        """
+        info = self._terminals.get(terminal_id)
+        if info is None:
+            raise RequestError.resource_not_found(terminal_id)
+        if info.session_id != session_id:
+            raise RequestError.invalid_request(
+                {"terminal_id": "terminal belongs to different session"}
+            )
+        return info
+
+    async def _read_terminal_output(self, terminal_id: str) -> None:
+        """
+        Background task to continuously read terminal output.
+
+        Reads from stdout and respects output_byte_limit with character
+        boundary truncation as required by the ACP protocol.
+        """
+        info = self._terminals.get(terminal_id)
+        if info is None or info.process.stdout is None:
+            return
+
+        try:
+            while True:
+                chunk = await info.process.stdout.read(4096)
+                if not chunk:
+                    break
+
+                # Check if we need to truncate
+                if info.output_byte_limit is not None:
+                    current_len = len(info.output_buffer)
+                    if current_len >= info.output_byte_limit:
+                        # Already at limit, mark as truncated but don't add more
+                        info.truncated = True
+                        continue
+
+                    remaining = info.output_byte_limit - current_len
+                    if len(chunk) > remaining:
+                        # Need to truncate - ensure we truncate at character boundary
+                        chunk = self._truncate_at_char_boundary(chunk, remaining)
+                        info.truncated = True
+
+                info.output_buffer.extend(chunk)
+
+            # Process has finished, capture exit status
+            exit_code = await info.process.wait()
+            info.exit_code = exit_code
+
+        except asyncio.CancelledError:
+            pass
+
+    def _truncate_at_char_boundary(self, data: bytes, max_bytes: int) -> bytes:
+        """
+        Truncate bytes at a valid UTF-8 character boundary.
+
+        The ACP protocol requires truncation at character boundaries to
+        maintain valid string output.
+        """
+        if max_bytes <= 0:
+            return b""
+
+        truncated = data[:max_bytes]
+
+        # Walk back from the end to find a valid UTF-8 boundary
+        # UTF-8 continuation bytes start with 10xxxxxx (0x80-0xBF)
+        while truncated and (truncated[-1] & 0xC0) == 0x80:
+            truncated = truncated[:-1]
+
+        # If we're at a lead byte of a multi-byte sequence that got cut off,
+        # remove it too
+        if truncated:
+            last_byte = truncated[-1]
+            # Check if it's a multi-byte lead byte (11xxxxxx)
+            if last_byte >= 0xC0:
+                # Count expected continuation bytes
+                if last_byte >= 0xF0:
+                    expected_len = 4
+                elif last_byte >= 0xE0:
+                    expected_len = 3
+                elif last_byte >= 0xC0:
+                    expected_len = 2
+                else:
+                    expected_len = 1
+
+                # Check if the sequence is complete in the original data
+                remaining_in_truncated = 1
+                if remaining_in_truncated < expected_len:
+                    # Incomplete sequence, remove the lead byte
+                    truncated = truncated[:-1]
+
+        return truncated
+
+    async def create_terminal(
+        self,
+        command: str,
+        session_id: str,
+        args: list[str] | None = None,
+        cwd: str | None = None,
+        env: list[EnvVariable] | None = None,
+        output_byte_limit: int | None = None,
+        **kwargs: Any,
+    ) -> CreateTerminalResponse:
+        """
+        Create a new terminal and start executing a command.
+
+        Returns immediately with a terminal_id; the command runs in the background.
+        """
+        # Validate command
+        if not command or not command.strip():
+            raise RequestError.invalid_params({"command": "command cannot be empty"})
+
+        # Validate cwd if provided
+        if cwd is not None:
+            if not os.path.isabs(cwd):
+                raise RequestError.invalid_params(
+                    {"cwd": "cwd must be an absolute path"}
+                )
+            if not os.path.isdir(cwd):
+                raise RequestError.invalid_params(
+                    {"cwd": "cwd directory does not exist"}
+                )
+
+        # Build environment dict
+        env_dict = None
+        if env:
+            env_dict = os.environ.copy()
+            for e in env:
+                env_dict[e.name] = e.value
+
+        # Build command arguments
+        cmd_args = [command] + (args or [])
+
+        try:
+            process = await asyncio.create_subprocess_exec(
+                *cmd_args,
+                cwd=cwd,
+                env=env_dict,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.STDOUT,  # Merge stderr into stdout
+            )
+        except FileNotFoundError:
+            raise RequestError.invalid_params(
+                {"command": f"command not found: {command}"}
+            )
+        except PermissionError:
+            raise RequestError.invalid_params(
+                {"command": f"permission denied: {command}"}
+            )
+        except OSError as e:
+            raise RequestError.internal_error(
+                {"command": command, "error": str(e)}
+            )
+
+        terminal_id = str(uuid.uuid4())
+        info = TerminalInfo(
+            process=process,
+            session_id=session_id,
+            output_byte_limit=output_byte_limit,
+        )
+        self._terminals[terminal_id] = info
+
+        # Start background task to read output
+        info._output_task = self._event_loop.create_task(
+            self._read_terminal_output(terminal_id)
+        )
+
+        return CreateTerminalResponse(terminal_id=terminal_id)
+
+    async def terminal_output(
+        self, session_id: str, terminal_id: str, **kwargs: Any
+    ) -> TerminalOutputResponse:
+        """
+        Retrieve current terminal output without blocking.
+
+        Returns the captured output so far, truncation status, and exit status
+        if the command has finished.
+        """
+        info = self._validate_terminal(terminal_id, session_id)
+
+        output = info.output_buffer.decode("utf-8", errors="replace")
+
+        # Build exit_status if process has finished
+        exit_status = None
+        if info.process.returncode is not None:
+            exit_status = TerminalExitStatus(
+                exit_code=info.exit_code,
+                signal=info.exit_signal,
+            )
+
+        return TerminalOutputResponse(
+            output=output,
+            truncated=info.truncated,
+            exit_status=exit_status,
+        )
+
+    async def wait_for_terminal_exit(
+        self, session_id: str, terminal_id: str, **kwargs: Any
+    ) -> WaitForTerminalExitResponse:
+        """
+        Block until the terminal command completes.
+
+        Returns the exit code and/or signal that terminated the process.
+        """
+        info = self._validate_terminal(terminal_id, session_id)
+
+        # Wait for the process to complete
+        exit_code = await info.process.wait()
+        info.exit_code = exit_code
+
+        return WaitForTerminalExitResponse(
+            exit_code=info.exit_code,
+            signal=info.exit_signal,
+        )
+
+    async def kill_terminal(
+        self, session_id: str, terminal_id: str, **kwargs: Any
+    ) -> KillTerminalCommandResponse | None:
+        """
+        Terminate a running command without releasing resources.
+
+        The terminal remains valid for subsequent terminal_output and
+        wait_for_terminal_exit calls. The agent must still call
+        release_terminal afterward.
+        """
+        info = self._validate_terminal(terminal_id, session_id)
+
+        if info.process.returncode is None:
+            # Process is still running, kill it
+            info.process.kill()
+            exit_code = await info.process.wait()
+            info.exit_code = exit_code
+            info.exit_signal = "SIGKILL"
+
+        return KillTerminalCommandResponse()
+
+    async def release_terminal(
+        self, session_id: str, terminal_id: str, **kwargs: Any
+    ) -> ReleaseTerminalResponse | None:
+        """
+        Kill any running command and deallocate all resources.
+
+        After release, the terminal_id becomes invalid.
+        """
+        info = self._validate_terminal(terminal_id, session_id)
+
+        # Kill process if still running
+        if info.process.returncode is None:
+            info.process.kill()
+            await info.process.wait()
+
+        # Cancel the output reading task if it's still running
+        if info._output_task is not None and not info._output_task.done():
+            info._output_task.cancel()
+            try:
+                await info._output_task
+            except asyncio.CancelledError:
+                pass
+
+        # Remove from tracking
+        del self._terminals[terminal_id]
+
+        return ReleaseTerminalResponse()
+
+    async def cleanup_session(self, session_id: str) -> None:
+        """
+        Clean up all terminals associated with a session.
+
+        Should be called when a session ends.
+        """
+        terminal_ids = [
+            tid for tid, info in self._terminals.items()
+            if info.session_id == session_id
+        ]
+        for terminal_id in terminal_ids:
+            try:
+                await self.release_terminal(session_id, terminal_id)
+            except Exception:
+                pass  # Best effort cleanup

jupyter_ai_acp_client/tests/__init__.py

@@ -0,0 +1 @@
+"""Python unit tests for jupyter_ai_acp_client."""

jupyter_ai_acp_client/tests/test_routes.py

@@ -0,0 +1,13 @@
+# import json
+
+from tornado.httpclient import HTTPClientError
+
+async def test_slash_commands_route_no_chat(jp_fetch):
+    """
+    Expects that the /ai/acp/slash_commands route returns a 400 when no ?chat_id
+    URL query argument is given.
+    """
+    try:
+        await jp_fetch("ai", "acp", "slash_commands")
+    except HTTPClientError as e:
+        assert e.code == 400

jupyter_ai_acp_client-0.0.1.data/data/etc/jupyter/jupyter_server_config.d/jupyter_ai_acp_client.json

@@ -0,0 +1,7 @@
+{
+  "ServerApp": {
+    "jpserver_extensions": {
+      "jupyter_ai_acp_client": true
+    }
+  }
+}

jupyter_ai_acp_client-0.0.1.data/data/share/jupyter/labextensions/@jupyter-ai/acp-client/install.json

@@ -0,0 +1,5 @@
+{
+  "packageManager": "python",
+  "packageName": "jupyter_ai_acp_client",
+  "uninstallInstructions": "Use your Python package manager (pip, conda, etc.) to uninstall the package jupyter_ai_acp_client"
+}