portacode 0.3.22__py3-none-any.whl → 0.3.24__py3-none-any.whl

portacode/_version.py

@@ -1,7 +1,14 @@
 # file generated by setuptools-scm
 # don't change, don't track in version control
 
-__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
@@ -9,13 +16,19 @@ if TYPE_CHECKING:
     from typing import Union
 
     VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
 else:
     VERSION_TUPLE = object
+    COMMIT_ID = object
 
 version: str
 __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
 
-__version__ = version = '0.3.22'
-__version_tuple__ = version_tuple = (0, 3, 22)
+__version__ = version = '0.3.24'
+__version_tuple__ = version_tuple = (0, 3, 24)
+
+__commit_id__ = commit_id = None

portacode/connection/handlers/WEBSOCKET_PROTOCOL.md

@@ -22,6 +22,7 @@ This document outlines the WebSocket communication protocol between the Portacod
     - [`file_create`](#file_create)
     - [`folder_create`](#folder_create)
     - [`file_rename`](#file_rename)
+    - [`content_request`](#content_request)
   - [Project State Actions](#project-state-actions)
     - [`project_state_folder_expand`](#project_state_folder_expand)
     - [`project_state_folder_collapse`](#project_state_folder_collapse)
@@ -29,6 +30,7 @@ This document outlines the WebSocket communication protocol between the Portacod
     - [`project_state_tab_close`](#project_state_tab_close)
     - [`project_state_set_active_tab`](#project_state_set_active_tab)
     - [`project_state_diff_open`](#project_state_diff_open)
+    - [`project_state_diff_content_request`](#project_state_diff_content_request)
     - [`project_state_git_stage`](#project_state_git_stage)
     - [`project_state_git_unstage`](#project_state_git_unstage)
     - [`project_state_git_revert`](#project_state_git_revert)
@@ -57,6 +59,7 @@ This document outlines the WebSocket communication protocol between the Portacod
     - [`file_create_response`](#file_create_response)
     - [`folder_create_response`](#folder_create_response)
     - [`file_rename_response`](#file_rename_response)
+    - [`content_response`](#content_response)
   - [Project State Events](#project-state-events)
     - [`project_state_initialized`](#project_state_initialized)
     - [`project_state_update`](#project_state_update)
@@ -66,6 +69,7 @@ This document outlines the WebSocket communication protocol between the Portacod
     - [`project_state_tab_close_response`](#project_state_tab_close_response)
     - [`project_state_set_active_tab_response`](#project_state_set_active_tab_response)
     - [`project_state_diff_open_response`](#project_state_diff_open_response)
+    - [`project_state_diff_content_response`](#project_state_diff_content_response)
     - [`project_state_git_stage_response`](#project_state_git_stage_response)
     - [`project_state_git_unstage_response`](#project_state_git_unstage_response)
     - [`project_state_git_revert_response`](#project_state_git_revert_response)
@@ -298,6 +302,20 @@ Renames a file or folder. Handled by [`file_rename`](./file_handlers.py).
 *   On success, the device will respond with a [`file_rename_response`](#file_rename_response) event.
 *   On error, a generic [`error`](#error) event is sent.
 
+### `content_request`
+
+Requests cached content by SHA-256 hash. This action is used to implement content caching for performance optimization, allowing clients to request large content (such as file content, HTML diffs, etc.) by hash instead of receiving it in every WebSocket message. For large content (>200KB), the response will be automatically chunked into multiple messages for reliable transmission. Handled by [`content_request`](./file_handlers.py).
+
+**Payload Fields:**
+
+*   `content_hash` (string, mandatory): The SHA-256 hash of the content to retrieve (with "sha256:" prefix).
+*   `request_id` (string, mandatory): A unique identifier for this request, used to match with the response.
+
+**Responses:**
+
+*   On success, the device will respond with one or more [`content_response`](#content_response) events containing the cached content. Large content is automatically chunked.
+*   On error (content not found), a [`content_response`](#content_response) event with `success: false` is sent.
+
 ## Project State Actions
 
 Project state actions manage the state of project folders, including file structures, Git metadata, open files, and folder expansion states. These actions provide real-time synchronization between the client and server for project management functionality.
@@ -408,14 +426,51 @@ Opens a diff tab for comparing file versions at different points in the git time
 *   On success, the device will respond with a [`project_state_diff_open_response`](#project_state_diff_open_response) event, followed by a [`project_state_update`](#project_state_update) event.
 *   On error, a generic [`error`](#error) event is sent.
 
+### `project_state_diff_content_request`
+
+Requests the content for a specific diff tab identified by its diff parameters. This action is used to load the actual file content (original and modified) as well as HTML diff data for diff tabs after they have been created by [`project_state_diff_open`](#project_state_diff_open). For large content (>200KB), the response will be automatically chunked into multiple messages for reliable transmission.
+
+**Content Types:** This action can request content for a diff:
+- `original`: The original (from) content of the diff
+- `modified`: The modified (to) content of the diff  
+- `html_diff`: The HTML diff versions for rich visual display
+- `all`: All content types returned as a single JSON object (recommended for efficiency)
+
+**Payload Fields:**
+
+*   `project_id` (string, mandatory): The project ID from the initialized project state.
+*   `file_path` (string, mandatory): The absolute path to the file the diff is for.
+*   `from_ref` (string, mandatory): The source reference point used in the diff. Must match the diff tab parameters.
+*   `to_ref` (string, mandatory): The target reference point used in the diff. Must match the diff tab parameters.
+*   `from_hash` (string, optional): The commit hash for `from_ref` if it was `"commit"`. Must match the diff tab parameters.
+*   `to_hash` (string, optional): The commit hash for `to_ref` if it was `"commit"`. Must match the diff tab parameters.
+*   `content_type` (string, mandatory): The type of content to request. Must be one of:
+    - `"original"`: Request the original (from) content
+    - `"modified"`: Request the modified (to) content
+    - `"html_diff"`: Request the HTML diff versions for visual display
+    - `"all"`: Request all content types as a single JSON object
+*   `request_id` (string, mandatory): Unique identifier for this request to match with the response.
+
+**Responses:**
+
+*   On success, the device will respond with one or more [`project_state_diff_content_response`](#project_state_diff_content_response) events. Large content is automatically chunked.
+*   On error, a generic [`error`](#error) event is sent.
+
 ### `project_state_git_stage`
 
-Stages a file for commit in the project's git repository. Handled by [`project_state_git_stage`](./project_state_handlers.py).
+Stages file(s) for commit in the project's git repository. Supports both single file and bulk operations. Handled by [`project_state_git_stage`](./project_state_handlers.py).
 
 **Payload Fields:**
 
 *   `project_id` (string, mandatory): The project ID from the initialized project state.
-*   `file_path` (string, mandatory): The absolute path to the file to stage.
+*   `file_path` (string, optional): The absolute path to a single file to stage. Used for backward compatibility.
+*   `file_paths` (array of strings, optional): Array of absolute paths to files to stage. Used for bulk operations.
+*   `stage_all` (boolean, optional): If true, stages all unstaged changes in the repository. Takes precedence over file_path/file_paths.
+
+**Operation Modes:**
+- Single file: Provide `file_path`
+- Bulk operation: Provide `file_paths` array  
+- Stage all: Set `stage_all` to true
 
 **Responses:**
 
@@ -424,12 +479,19 @@ Stages a file for commit in the project's git repository. Handled by [`project_s
 
 ### `project_state_git_unstage`
 
-Unstages a file (removes from staging area) in the project's git repository. Handled by [`project_state_git_unstage`](./project_state_handlers.py).
+Unstages file(s) (removes from staging area) in the project's git repository. Supports both single file and bulk operations. Handled by [`project_state_git_unstage`](./project_state_handlers.py).
 
 **Payload Fields:**
 
 *   `project_id` (string, mandatory): The project ID from the initialized project state.
-*   `file_path` (string, mandatory): The absolute path to the file to unstage.
+*   `file_path` (string, optional): The absolute path to a single file to unstage. Used for backward compatibility.
+*   `file_paths` (array of strings, optional): Array of absolute paths to files to unstage. Used for bulk operations.
+*   `unstage_all` (boolean, optional): If true, unstages all staged changes in the repository. Takes precedence over file_path/file_paths.
+
+**Operation Modes:**
+- Single file: Provide `file_path`
+- Bulk operation: Provide `file_paths` array  
+- Unstage all: Set `unstage_all` to true
 
 **Responses:**
 
@@ -438,12 +500,19 @@ Unstages a file (removes from staging area) in the project's git repository. Han
 
 ### `project_state_git_revert`
 
-Reverts a file to its HEAD version, discarding local changes in the project's git repository. Handled by [`project_state_git_revert`](./project_state_handlers.py).
+Reverts file(s) to their HEAD version, discarding local changes in the project's git repository. Supports both single file and bulk operations. Handled by [`project_state_git_revert`](./project_state_handlers.py).
 
 **Payload Fields:**
 
 *   `project_id` (string, mandatory): The project ID from the initialized project state.
-*   `file_path` (string, mandatory): The absolute path to the file to revert.
+*   `file_path` (string, optional): The absolute path to a single file to revert. Used for backward compatibility.
+*   `file_paths` (array of strings, optional): Array of absolute paths to files to revert. Used for bulk operations.
+*   `revert_all` (boolean, optional): If true, reverts all unstaged changes in the repository. Takes precedence over file_path/file_paths.
+
+**Operation Modes:**
+- Single file: Provide `file_path`
+- Bulk operation: Provide `file_paths` array  
+- Revert all: Set `revert_all` to true
 
 **Responses:**
 
@@ -713,6 +782,68 @@ Confirms that a file or folder has been renamed successfully in response to a `f
 *   `is_directory` (boolean, mandatory): Indicates whether the renamed item is a directory.
 *   `success` (boolean, mandatory): Indicates whether the rename was successful.
 
+### <a name="content_response"></a>`content_response`
+
+Returns cached content in response to a `content_request` action. This is part of the content caching system used for performance optimization. For large content (>200KB), the response is automatically chunked into multiple messages to ensure reliable transmission over WebSocket connections. Handled by [`content_request`](./file_handlers.py).
+
+**Event Fields:**
+
+*   `request_id` (string, mandatory): The unique identifier from the corresponding request, used to match request and response.
+*   `content_hash` (string, mandatory): The SHA-256 hash that was requested.
+*   `content` (string, optional): The cached content or chunk content if found and `success` is true. Null if content was not found.
+*   `success` (boolean, mandatory): Indicates whether the content was found and returned successfully.
+*   `error` (string, optional): Error message if `success` is false (e.g., "Content not found in cache").
+*   `chunked` (boolean, mandatory): Indicates whether this response is part of a chunked transfer. False for single responses, true for chunked responses.
+
+**Chunked Transfer Fields (when `chunked` is true):**
+
+*   `transfer_id` (string, mandatory): Unique identifier for the chunked transfer session.
+*   `chunk_index` (integer, mandatory): Zero-based index of this chunk in the sequence.
+*   `chunk_count` (integer, mandatory): Total number of chunks in the transfer.
+*   `chunk_size` (integer, mandatory): Size of this chunk in bytes.
+*   `total_size` (integer, mandatory): Total size of the complete content in bytes.
+*   `chunk_hash` (string, mandatory): SHA-256 hash of this chunk for verification.
+*   `is_final_chunk` (boolean, mandatory): Indicates if this is the last chunk in the sequence.
+
+**Chunked Transfer Process:**
+
+1. **Size Check**: Content >200KB is automatically chunked into 64KB chunks
+2. **Sequential Delivery**: Chunks are sent in order with increasing `chunk_index`
+3. **Client Assembly**: Client collects all chunks and verifies integrity using hashes
+4. **Hash Verification**: Both individual chunk hashes and final content hash are verified
+5. **Error Handling**: Missing chunks or hash mismatches trigger request failure
+
+**Example Non-Chunked Response:**
+```json
+{
+  "event": "content_response",
+  "request_id": "req_abc123",
+  "content_hash": "sha256:...",
+  "content": "Small content here",
+  "success": true,
+  "chunked": false
+}
+```
+
+**Example Chunked Response (first chunk):**
+```json
+{
+  "event": "content_response", 
+  "request_id": "req_abc123",
+  "content_hash": "sha256:...",
+  "content": "First chunk content...",
+  "success": true,
+  "chunked": true,
+  "transfer_id": "transfer_xyz789",
+  "chunk_index": 0,
+  "chunk_count": 5,
+  "chunk_size": 65536,
+  "total_size": 300000,
+  "chunk_hash": "chunk_sha256:...",
+  "is_final_chunk": false
+}
+```
+
 ### Project State Events
 
 ### <a name="project_state_initialized"></a>`project_state_initialized`
@@ -752,13 +883,17 @@ Confirms that project state has been successfully initialized for a client sessi
     *   `tab_type` (string, mandatory): Type of tab ("file", "diff", "untitled", "image", "audio", "video").
     *   `title` (string, mandatory): Display title for the tab.
     *   `file_path` (string, optional): Path for file-based tabs.
-    *   `content` (string, optional): Text content or base64 for media.
-    *   `original_content` (string, optional): For diff tabs - original content.
-    *   `modified_content` (string, optional): For diff tabs - modified content.
+    *   `content` (string, optional): Text content or base64 for media. When content caching is enabled, this field may be excluded from project state events if the content is available via `content_hash`.
+    *   `original_content` (string, optional): For diff tabs - original content. When content caching is enabled, this field may be excluded from project state events if the content is available via `original_content_hash`.
+    *   `modified_content` (string, optional): For diff tabs - modified content. When content caching is enabled, this field may be excluded from project state events if the content is available via `modified_content_hash`.
     *   `is_dirty` (boolean, mandatory): Whether the tab has unsaved changes.
     *   `mime_type` (string, optional): MIME type for media files.
     *   `encoding` (string, optional): Content encoding (base64, utf-8, etc.).
-    *   `metadata` (object, optional): Additional metadata.
+    *   `metadata` (object, optional): Additional metadata. When content caching is enabled, large metadata such as `html_diff_versions` may be excluded from project state events if available via `html_diff_hash`.
+    *   `content_hash` (string, optional): SHA-256 hash of the tab content for content caching optimization. When present, the content can be retrieved via [`content_request`](#content_request) action.
+    *   `original_content_hash` (string, optional): SHA-256 hash of the original content for diff tabs. When present, the original content can be retrieved via [`content_request`](#content_request) action.
+    *   `modified_content_hash` (string, optional): SHA-256 hash of the modified content for diff tabs. When present, the modified content can be retrieved via [`content_request`](#content_request) action.
+    *   `html_diff_hash` (string, optional): SHA-256 hash of the HTML diff versions JSON for diff tabs. When present, the HTML diff data can be retrieved via [`content_request`](#content_request) action as a JSON string.
 *   `active_tab` (object, optional): The currently active tab object, or null if no tab is active.
 *   `items` (array, mandatory): Flattened array of all visible file/folder items. Always includes root level items and one level down from the project root (since the project root is treated as expanded by default). Also includes items within explicitly expanded folders and one level down from each expanded folder. Each item object contains the following fields:
     *   `name` (string, mandatory): The file or directory name.
@@ -872,36 +1007,73 @@ Confirms the result of opening a diff tab with git timeline references.
 *   `success` (boolean, mandatory): Whether the diff tab creation was successful.
 *   `error` (string, optional): Error message if the operation failed.
 
+### <a name="project_state_diff_content_response"></a>`project_state_diff_content_response`
+
+Returns the requested content for a specific diff tab, sent in response to a [`project_state_diff_content_request`](#project_state_diff_content_request) action. For large content (>200KB), the response is automatically chunked into multiple messages to ensure reliable transmission over WebSocket connections.
+
+**Event Fields:**
+
+*   `project_id` (string, mandatory): The project ID the operation was performed on.
+*   `file_path` (string, mandatory): The path to the file the diff content is for.
+*   `from_ref` (string, mandatory): The source reference point used in the diff.
+*   `to_ref` (string, mandatory): The target reference point used in the diff.
+*   `from_hash` (string, optional): The commit hash used for `from_ref` if it was `"commit"`.
+*   `to_hash` (string, optional): The commit hash used for `to_ref` if it was `"commit"`.
+*   `content_type` (string, mandatory): The type of content being returned (`"original"`, `"modified"`, `"html_diff"`, or `"all"`).
+*   `request_id` (string, mandatory): The unique identifier from the request to match response with request.
+*   `success` (boolean, mandatory): Whether the content retrieval was successful.
+*   `content` (string, optional): The requested content or chunk content. For `html_diff` type, this is a JSON string containing the HTML diff versions object. For `all` type, this is a JSON string containing an object with `original_content`, `modified_content`, and `html_diff_versions` fields.
+*   `error` (string, optional): Error message if the operation failed.
+*   `chunked` (boolean, mandatory): Indicates whether this response is part of a chunked transfer. False for single responses, true for chunked responses.
+
+**Chunked Transfer Fields (when `chunked` is true):**
+
+*   `transfer_id` (string, mandatory): Unique identifier for the chunked transfer session.
+*   `chunk_index` (integer, mandatory): Zero-based index of this chunk in the sequence.
+*   `chunk_count` (integer, mandatory): Total number of chunks in the transfer.
+*   `chunk_size` (integer, mandatory): Size of this chunk in bytes.
+*   `total_size` (integer, mandatory): Total size of the complete content in bytes.
+*   `chunk_hash` (string, mandatory): SHA-256 hash of this chunk for verification.
+*   `is_final_chunk` (boolean, mandatory): Indicates if this is the last chunk in the sequence.
+
+**Note:** The chunked transfer process follows the same pattern as described in [`content_response`](#content_response), with content >200KB automatically split into 64KB chunks for reliable transmission.
+
 ### <a name="project_state_git_stage_response"></a>`project_state_git_stage_response`
 
-Confirms the result of a git stage operation.
+Confirms the result of a git stage operation. Supports responses for both single file and bulk operations.
 
 **Event Fields:**
 
 *   `project_id` (string, mandatory): The project ID the operation was performed on.
-*   `file_path` (string, mandatory): The path to the file that was staged.
+*   `file_path` (string, optional): The path to the file that was staged (for single file operations).
+*   `file_paths` (array of strings, optional): Array of paths to files that were staged (for bulk operations).
+*   `stage_all` (boolean, optional): Present if the operation was a "stage all" operation.
 *   `success` (boolean, mandatory): Whether the stage operation was successful.
 *   `error` (string, optional): Error message if the operation failed.
 
 ### <a name="project_state_git_unstage_response"></a>`project_state_git_unstage_response`
 
-Confirms the result of a git unstage operation.
+Confirms the result of a git unstage operation. Supports responses for both single file and bulk operations.
 
 **Event Fields:**
 
 *   `project_id` (string, mandatory): The project ID the operation was performed on.
-*   `file_path` (string, mandatory): The path to the file that was unstaged.
+*   `file_path` (string, optional): The path to the file that was unstaged (for single file operations).
+*   `file_paths` (array of strings, optional): Array of paths to files that were unstaged (for bulk operations).
+*   `unstage_all` (boolean, optional): Present if the operation was an "unstage all" operation.
 *   `success` (boolean, mandatory): Whether the unstage operation was successful.
 *   `error` (string, optional): Error message if the operation failed.
 
 ### <a name="project_state_git_revert_response"></a>`project_state_git_revert_response`
 
-Confirms the result of a git revert operation.
+Confirms the result of a git revert operation. Supports responses for both single file and bulk operations.
 
 **Event Fields:**
 
 *   `project_id` (string, mandatory): The project ID the operation was performed on.
-*   `file_path` (string, mandatory): The path to the file that was reverted.
+*   `file_path` (string, optional): The path to the file that was reverted (for single file operations).
+*   `file_paths` (array of strings, optional): Array of paths to files that were reverted (for bulk operations).
+*   `revert_all` (boolean, optional): Present if the operation was a "revert all" operation.
 *   `success` (boolean, mandatory): Whether the revert operation was successful.
 *   `error` (string, optional): Error message if the operation failed.
 

portacode/connection/handlers/__init__.py

@@ -23,6 +23,7 @@ from .file_handlers import (
     FileCreateHandler,
     FolderCreateHandler,
     FileRenameHandler,
+    ContentRequestHandler,
 )
 from .project_state_handlers import (
     ProjectStateFolderExpandHandler,
@@ -31,6 +32,7 @@ from .project_state_handlers import (
     ProjectStateTabCloseHandler,
     ProjectStateSetActiveTabHandler,
     ProjectStateDiffOpenHandler,
+    ProjectStateDiffContentHandler,
     ProjectStateGitStageHandler,
     ProjectStateGitUnstageHandler,
     ProjectStateGitRevertHandler,
@@ -56,6 +58,7 @@ __all__ = [
     "FileCreateHandler",
     "FolderCreateHandler",
     "FileRenameHandler",
+    "ContentRequestHandler",
     # Project state handlers
     "ProjectStateFolderExpandHandler",
     "ProjectStateFolderCollapseHandler",
@@ -63,6 +66,7 @@ __all__ = [
     "ProjectStateTabCloseHandler",
     "ProjectStateSetActiveTabHandler",
     "ProjectStateDiffOpenHandler",
+    "ProjectStateDiffContentHandler",
     "ProjectStateGitStageHandler",
     "ProjectStateGitUnstageHandler",
     "ProjectStateGitRevertHandler",

portacode/connection/handlers/base.py

@@ -114,11 +114,15 @@ class AsyncHandler(BaseHandler):
             response = await self.execute(message)
             logger.info("handler: Command %s executed successfully", self.command_name)
             
-            # Extract project_id from response for session targeting
-            project_id = response.get("project_id")
-            logger.info("handler: %s response project_id=%s, response=%s", 
-                       self.command_name, project_id, response)
-            await self.send_response(response, reply_channel, project_id)
+            # Handle cases where execute() sends responses directly and returns None
+            if response is not None:
+                # Extract project_id from response for session targeting
+                project_id = response.get("project_id")
+                logger.info("handler: %s response project_id=%s, response=%s", 
+                           self.command_name, project_id, response)
+                await self.send_response(response, reply_channel, project_id)
+            else:
+                logger.info("handler: %s handled response transmission directly", self.command_name)
         except Exception as exc:
             logger.exception("handler: Error in async handler %s: %s", self.command_name, exc)
             # Extract project_id from original message for error targeting

portacode/connection/handlers/chunked_content.py

@@ -0,0 +1,244 @@
+"""
+Chunked content transfer utilities for handling large content over WebSocket.
+
+This module provides functionality to split large content into chunks for reliable
+transmission over WebSocket connections, and to reassemble chunks on the client side.
+"""
+
+import hashlib
+import uuid
+from typing import Dict, Any, List, Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Maximum size for content before chunking (200KB)
+MAX_CONTENT_SIZE = 200 * 1024  # 200KB
+
+# Maximum chunk size (64KB per chunk for reliable WebSocket transmission)
+CHUNK_SIZE = 64 * 1024  # 64KB
+
+
+def should_chunk_content(content: str) -> bool:
+    """Determine if content should be chunked based on size."""
+    if content is None:
+        return False
+    
+    content_bytes = content.encode('utf-8')
+    return len(content_bytes) > MAX_CONTENT_SIZE
+
+
+def calculate_content_hash(content: str) -> str:
+    """Calculate SHA-256 hash of content for verification."""
+    if content is None:
+        return ""
+    
+    content_bytes = content.encode('utf-8')
+    return hashlib.sha256(content_bytes).hexdigest()
+
+
+def split_content_into_chunks(content: str, transfer_id: Optional[str] = None) -> List[Dict[str, Any]]:
+    """
+    Split content into chunks for transmission.
+    
+    Args:
+        content: The content to split
+        transfer_id: Optional transfer ID, will generate one if not provided
+        
+    Returns:
+        List of chunk dictionaries ready for transmission
+    """
+    if content is None:
+        return []
+    
+    if transfer_id is None:
+        transfer_id = str(uuid.uuid4())
+    
+    content_bytes = content.encode('utf-8')
+    total_size = len(content_bytes)
+    content_hash = hashlib.sha256(content_bytes).hexdigest()
+    
+    chunks = []
+    chunk_index = 0
+    offset = 0
+    
+    while offset < len(content_bytes):
+        chunk_data = content_bytes[offset:offset + CHUNK_SIZE]
+        chunk_content = chunk_data.decode('utf-8')
+        chunk_hash = hashlib.sha256(chunk_data).hexdigest()
+        
+        chunks.append({
+            "transfer_id": transfer_id,
+            "chunk_index": chunk_index,
+            "chunk_count": (total_size + CHUNK_SIZE - 1) // CHUNK_SIZE,  # Ceiling division
+            "chunk_size": len(chunk_data),
+            "total_size": total_size,
+            "content_hash": content_hash,
+            "chunk_hash": chunk_hash,
+            "chunk_content": chunk_content,
+            "is_final_chunk": offset + CHUNK_SIZE >= len(content_bytes)
+        })
+        
+        chunk_index += 1
+        offset += CHUNK_SIZE
+    
+    logger.info(f"Split content into {len(chunks)} chunks (total size: {total_size} bytes, transfer_id: {transfer_id})")
+    return chunks
+
+
+def create_chunked_response(base_response: Dict[str, Any], content_field: str, content: str) -> List[Dict[str, Any]]:
+    """
+    Create chunked response messages from a base response and content.
+    
+    Args:
+        base_response: The base response dictionary
+        content_field: The field name where content should be placed
+        content: The content to chunk
+        
+    Returns:
+        List of response dictionaries with chunked content
+    """
+    if not should_chunk_content(content):
+        # Content is small enough, return as single response
+        response = base_response.copy()
+        response[content_field] = content
+        response["chunked"] = False
+        return [response]
+    
+    # Content needs chunking
+    transfer_id = str(uuid.uuid4())
+    chunks = split_content_into_chunks(content, transfer_id)
+    responses = []
+    
+    for chunk in chunks:
+        response = base_response.copy()
+        response["chunked"] = True
+        response["transfer_id"] = chunk["transfer_id"]
+        response["chunk_index"] = chunk["chunk_index"]
+        response["chunk_count"] = chunk["chunk_count"]
+        response["chunk_size"] = chunk["chunk_size"]
+        response["total_size"] = chunk["total_size"]
+        response["content_hash"] = chunk["content_hash"]
+        response["chunk_hash"] = chunk["chunk_hash"]
+        response["is_final_chunk"] = chunk["is_final_chunk"]
+        response[content_field] = chunk["chunk_content"]
+        
+        responses.append(response)
+    
+    logger.info(f"Created chunked response with {len(responses)} chunks for transfer_id: {transfer_id}")
+    return responses
+
+
+class ChunkAssembler:
+    """
+    Helper class to assemble chunked content on the receiving side.
+    """
+    
+    def __init__(self):
+        self.transfers: Dict[str, Dict[str, Any]] = {}
+    
+    def add_chunk(self, chunk_data: Dict[str, Any], content_field: str) -> Optional[str]:
+        """
+        Add a chunk to the assembler.
+        
+        Args:
+            chunk_data: The chunk data dictionary
+            content_field: The field name containing the chunk content
+            
+        Returns:
+            Complete content if all chunks received, None if more chunks needed
+            
+        Raises:
+            ValueError: If chunk data is invalid or verification fails
+        """
+        transfer_id = chunk_data.get("transfer_id")
+        chunk_index = chunk_data.get("chunk_index")
+        chunk_count = chunk_data.get("chunk_count")
+        chunk_size = chunk_data.get("chunk_size")
+        total_size = chunk_data.get("total_size")
+        content_hash = chunk_data.get("content_hash")
+        chunk_hash = chunk_data.get("chunk_hash")
+        chunk_content = chunk_data.get(content_field)
+        is_final_chunk = chunk_data.get("is_final_chunk")
+        
+        if not all([transfer_id, chunk_index is not None, chunk_count, chunk_size, 
+                   total_size, content_hash, chunk_hash, chunk_content is not None]):
+            raise ValueError("Missing required chunk fields")
+        
+        # Verify chunk content hash
+        chunk_bytes = chunk_content.encode('utf-8')
+        if len(chunk_bytes) != chunk_size:
+            raise ValueError(f"Chunk size mismatch: expected {chunk_size}, got {len(chunk_bytes)}")
+        
+        calculated_chunk_hash = hashlib.sha256(chunk_bytes).hexdigest()
+        if calculated_chunk_hash != chunk_hash:
+            raise ValueError(f"Chunk hash mismatch: expected {chunk_hash}, got {calculated_chunk_hash}")
+        
+        # Initialize transfer if not exists
+        if transfer_id not in self.transfers:
+            self.transfers[transfer_id] = {
+                "chunk_count": chunk_count,
+                "total_size": total_size,
+                "content_hash": content_hash,
+                "chunks": {},
+                "received_chunks": 0
+            }
+        
+        transfer = self.transfers[transfer_id]
+        
+        # Verify transfer metadata consistency
+        if (transfer["chunk_count"] != chunk_count or 
+            transfer["total_size"] != total_size or 
+            transfer["content_hash"] != content_hash):
+            raise ValueError("Transfer metadata mismatch")
+        
+        # Store chunk if not already received
+        if chunk_index not in transfer["chunks"]:
+            transfer["chunks"][chunk_index] = chunk_content
+            transfer["received_chunks"] += 1
+            
+            logger.debug(f"Received chunk {chunk_index + 1}/{chunk_count} for transfer {transfer_id}")
+        
+        # Check if all chunks received
+        if transfer["received_chunks"] == chunk_count:
+            # Assemble content
+            assembled_content = ""
+            for i in range(chunk_count):
+                if i not in transfer["chunks"]:
+                    raise ValueError(f"Missing chunk {i} for transfer {transfer_id}")
+                assembled_content += transfer["chunks"][i]
+            
+            # Verify final content hash
+            assembled_bytes = assembled_content.encode('utf-8')
+            if len(assembled_bytes) != total_size:
+                raise ValueError(f"Final content size mismatch: expected {total_size}, got {len(assembled_bytes)}")
+            
+            calculated_hash = hashlib.sha256(assembled_bytes).hexdigest()
+            if calculated_hash != content_hash:
+                raise ValueError(f"Final content hash mismatch: expected {content_hash}, got {calculated_hash}")
+            
+            # Clean up transfer
+            del self.transfers[transfer_id]
+            
+            logger.info(f"Successfully assembled content from {chunk_count} chunks (transfer_id: {transfer_id}, size: {total_size} bytes)")
+            return assembled_content
+        
+        return None  # More chunks needed
+    
+    def cleanup_stale_transfers(self, max_age_seconds: int = 300):
+        """Clean up transfers older than max_age_seconds."""
+        import time
+        current_time = time.time()
+        
+        stale_transfers = []
+        for transfer_id, transfer in self.transfers.items():
+            # Add timestamp if not exists
+            if "start_time" not in transfer:
+                transfer["start_time"] = current_time
+            
+            if current_time - transfer["start_time"] > max_age_seconds:
+                stale_transfers.append(transfer_id)
+        
+        for transfer_id in stale_transfers:
+            logger.warning(f"Cleaning up stale transfer: {transfer_id}")
+            del self.transfers[transfer_id]