griptape-nodes 0.62.2__py3-none-any.whl → 0.63.0__py3-none-any.whl

griptape_nodes/retained_mode/events/agent_events.py

@@ -29,6 +29,7 @@ class RunAgentRequest(RequestPayload):
     Args:
         input: Text input to send to the agent
         url_artifacts: List of URL artifacts to include with the request
+        thread_id: Thread ID to use for conversation.
         additional_mcp_servers: List of additional MCP server names to include
 
     Results: RunAgentResultStarted -> RunAgentResultSuccess (with output) | RunAgentResultFailure (execution error)
@@ -36,6 +37,7 @@ class RunAgentRequest(RequestPayload):
 
     input: str
     url_artifacts: list[RunAgentRequestArtifact]
+    thread_id: str
     additional_mcp_servers: list[str] = field(default_factory=list)
 
 
@@ -52,9 +54,11 @@ class RunAgentResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
 
     Args:
         output: Dictionary containing agent response and execution results
+        thread_id: The thread ID used for this conversation
     """
 
     output: dict
+    thread_id: str
 
 
 @dataclass
@@ -77,9 +81,14 @@ class GetConversationMemoryRequest(RequestPayload):
     Use when: Reviewing conversation history, implementing memory inspection,
     debugging agent behavior, displaying conversation context.
 
+    Args:
+        thread_id: Thread ID to retrieve memory from.
+
     Results: GetConversationMemoryResultSuccess (with runs) | GetConversationMemoryResultFailure (memory error)
     """
 
+    thread_id: str
+
 
 @dataclass
 @PayloadRegistry.register
@@ -88,9 +97,11 @@ class GetConversationMemoryResultSuccess(WorkflowNotAlteredMixin, ResultPayloadS
 
     Args:
         runs: List of conversation runs (exchanges between user and agent)
+        thread_id: The thread ID for this conversation memory
     """
 
     runs: list[Run]
+    thread_id: str
 
 
 @dataclass
@@ -130,26 +141,238 @@ class ConfigureAgentResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure)
 
 @dataclass
 @PayloadRegistry.register
-class ResetAgentConversationMemoryRequest(RequestPayload):
-    """Reset the agent's conversation memory.
+class CreateThreadRequest(RequestPayload):
+    """Create a new conversation thread.
+
+    Use when: Starting a new conversation, initializing thread storage,
+    creating named conversation contexts.
+
+    Args:
+        title: Optional title for the thread. If not provided, will be auto-generated from first message.
+        local_id: Optional local identifier to store in thread metadata.
+
+    Results: CreateThreadResultSuccess (with thread_id) | CreateThreadResultFailure (creation error)
+    """
 
-    Use when: Starting fresh conversations, clearing conversation history,
-    resolving memory issues, implementing conversation reset features.
+    title: str | None = None
+    local_id: str | None = None
 
-    Results: ResetAgentConversationMemoryResultSuccess | ResetAgentConversationMemoryResultFailure (reset error)
+
+@dataclass
+@PayloadRegistry.register
+class CreateThreadResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Thread created successfully.
+
+    Args:
+        thread_id: Unique identifier for the created thread
+        title: Thread title (may be None if not provided and no messages yet)
+        created_at: ISO timestamp when thread was created
+        updated_at: ISO timestamp when thread was last updated
     """
 
+    thread_id: str
+    title: str | None
+    created_at: str
+    updated_at: str
+
 
 @dataclass
 @PayloadRegistry.register
-class ResetAgentConversationMemoryResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
-    """Agent conversation memory reset successfully. All previous conversation history cleared."""
+class CreateThreadResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Thread creation failed. Common causes: storage error, invalid parameters."""
+
+
+@dataclass
+@PayloadRegistry.register
+class ListThreadsRequest(RequestPayload):
+    """List all conversation threads.
+
+    Use when: Displaying thread list, retrieving available conversations,
+    implementing thread selection UI.
+
+    Results: ListThreadsResultSuccess (with threads) | ListThreadsResultFailure (retrieval error)
+    """
+
+
+@dataclass
+class ThreadMetadata:
+    """Metadata for a conversation thread."""
+
+    thread_id: str
+    title: str | None
+    created_at: str
+    updated_at: str
+    message_count: int
+    archived: bool
+    local_id: str | None = None
+
+
+@dataclass
+@PayloadRegistry.register
+class ListThreadsResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Threads retrieved successfully.
+
+    Args:
+        threads: List of thread metadata objects
+    """
+
+    threads: list[ThreadMetadata]
+
+
+@dataclass
+@PayloadRegistry.register
+class ListThreadsResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Thread listing failed. Common causes: storage error, permission error."""
+
+
+@dataclass
+@PayloadRegistry.register
+class DeleteThreadRequest(RequestPayload):
+    """Delete a conversation thread permanently.
+
+    Use when: Removing unwanted conversations, cleaning up storage,
+    implementing thread deletion UI.
+
+    Args:
+        thread_id: ID of the thread to delete
+
+    Results: DeleteThreadResultSuccess | DeleteThreadResultFailure (deletion error)
+    """
+
+    thread_id: str
+
+
+@dataclass
+@PayloadRegistry.register
+class DeleteThreadResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Thread deleted successfully.
+
+    Args:
+        thread_id: ID of the deleted thread
+    """
+
+    thread_id: str
+
+
+@dataclass
+@PayloadRegistry.register
+class DeleteThreadResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Thread deletion failed. Common causes: thread not found, storage error."""
+
+
+@dataclass
+@PayloadRegistry.register
+class RenameThreadRequest(RequestPayload):
+    """Rename an existing thread.
+
+    Use when: Updating thread titles, organizing conversations,
+    implementing thread editing UI.
+
+    Args:
+        thread_id: ID of the thread to rename
+        new_title: New title for the thread
+
+    Results: RenameThreadResultSuccess | RenameThreadResultFailure (rename error)
+    """
+
+    thread_id: str
+    new_title: str
+
+
+@dataclass
+@PayloadRegistry.register
+class RenameThreadResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Thread renamed successfully.
+
+    Args:
+        thread_id: ID of the renamed thread
+        title: New title of the thread
+        updated_at: ISO timestamp when thread was updated
+    """
+
+    thread_id: str
+    title: str
+    updated_at: str
+
+
+@dataclass
+@PayloadRegistry.register
+class RenameThreadResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Thread rename failed. Common causes: thread not found, storage error."""
+
+
+@dataclass
+@PayloadRegistry.register
+class ArchiveThreadRequest(RequestPayload):
+    """Archive a conversation thread.
+
+    Use when: Organizing conversations, hiding inactive threads,
+    cleaning up thread list without permanently deleting.
+
+    Args:
+        thread_id: ID of the thread to archive
+
+    Results: ArchiveThreadResultSuccess | ArchiveThreadResultFailure (archive error)
+    """
+
+    thread_id: str
+
+
+@dataclass
+@PayloadRegistry.register
+class ArchiveThreadResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Thread archived successfully.
+
+    Args:
+        thread_id: ID of the archived thread
+        updated_at: ISO timestamp when thread was updated
+    """
+
+    thread_id: str
+    updated_at: str
+
+
+@dataclass
+@PayloadRegistry.register
+class ArchiveThreadResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Thread archive failed. Common causes: thread not found, already archived, storage error."""
+
+
+@dataclass
+@PayloadRegistry.register
+class UnarchiveThreadRequest(RequestPayload):
+    """Unarchive a conversation thread.
+
+    Use when: Restoring archived conversations, resuming old threads,
+    making archived threads active again.
+
+    Args:
+        thread_id: ID of the thread to unarchive
+
+    Results: UnarchiveThreadResultSuccess | UnarchiveThreadResultFailure (unarchive error)
+    """
+
+    thread_id: str
+
+
+@dataclass
+@PayloadRegistry.register
+class UnarchiveThreadResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Thread unarchived successfully.
+
+    Args:
+        thread_id: ID of the unarchived thread
+        updated_at: ISO timestamp when thread was updated
+    """
+
+    thread_id: str
+    updated_at: str
 
 
 @dataclass
 @PayloadRegistry.register
-class ResetAgentConversationMemoryResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    """Agent conversation memory reset failed. Common causes: memory access error, system constraints."""
+class UnarchiveThreadResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Thread unarchive failed. Common causes: thread not found, not archived, storage error."""
 
 
 @dataclass

griptape_nodes/retained_mode/events/app_events.py

@@ -1,4 +1,5 @@
 from dataclasses import dataclass, field
+from enum import StrEnum
 
 from griptape_nodes.retained_mode.events.base_events import (
     AppPayload,
@@ -11,6 +12,21 @@ from griptape_nodes.retained_mode.events.base_events import (
 from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
 
 
+class InitializationPhase(StrEnum):
+    """Initialization phase types for engine startup."""
+
+    LIBRARIES = "libraries"
+    WORKFLOWS = "workflows"
+
+
+class InitializationStatus(StrEnum):
+    """Status types for initialization progress."""
+
+    LOADING = "loading"
+    COMPLETE = "complete"
+    FAILED = "failed"
+
+
 @dataclass
 class OrganizationInfo:
     """Organization information from Griptape Cloud."""
@@ -104,6 +120,28 @@ class AppConnectionEstablished(AppPayload):
     """Notification that a connection to the API has been established."""
 
 
+@dataclass
+@PayloadRegistry.register
+class EngineInitializationProgress(AppPayload):
+    """Real-time progress updates during engine initialization (libraries and workflows loading).
+
+    Args:
+        phase: Current initialization phase (libraries or workflows)
+        item_name: Name of the library or workflow being loaded
+        status: Current status of the item (loading, complete, or failed)
+        current: Number of items completed so far
+        total: Total number of items to load
+        error: Error message if status is failed, None otherwise
+    """
+
+    phase: InitializationPhase
+    item_name: str
+    status: InitializationStatus
+    current: int
+    total: int
+    error: str | None = None
+
+
 @dataclass
 @PayloadRegistry.register
 class GetEngineVersionRequest(RequestPayload):

griptape_nodes/retained_mode/events/library_events.py

@@ -14,6 +14,7 @@ from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
 
 if TYPE_CHECKING:
     from griptape_nodes.node_library.library_registry import LibraryMetadata, LibrarySchema, NodeMetadata
+    from griptape_nodes.retained_mode.managers.fitness_problems.libraries import LibraryProblem
     from griptape_nodes.retained_mode.managers.library_lifecycle.library_status import LibraryStatus
 
 
@@ -201,14 +202,14 @@ class LoadLibraryMetadataFromFileResultFailure(WorkflowNotAlteredMixin, ResultPa
                      None if the name couldn't be determined.
         status: The LibraryStatus enum indicating the type of failure
                (MISSING, UNUSABLE, etc.).
-        problems: List of specific error messages describing what went wrong
-                 during loading (JSON parse errors, validation failures, etc.).
+        problems: List of specific problems encountered during loading
+                 (file not found, JSON parse errors, validation failures, etc.).
     """
 
     library_path: str
     library_name: str | None
     status: LibraryStatus
-    problems: list[str]
+    problems: list[LibraryProblem]
 
 
 @dataclass
@@ -510,3 +511,31 @@ class ReloadAllLibrariesResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess
 @PayloadRegistry.register
 class ReloadAllLibrariesResultFailure(ResultPayloadFailure):
     """Library reload failed. Common causes: library loading errors, system constraints, initialization failures."""
+
+
+@dataclass
+@PayloadRegistry.register
+class LoadLibrariesRequest(RequestPayload):
+    """Load all libraries from configuration if they are not already loaded.
+
+    This is a non-destructive operation that checks if libraries are already loaded
+    and only performs the initial loading if needed. Unlike ReloadAllLibrariesRequest,
+    this does NOT clear any workflow state.
+
+    Use when: Ensuring libraries are loaded at workflow startup, initializing library
+    system on demand, preparing library catalog without disrupting existing workflows.
+
+    Results: LoadLibrariesResultSuccess | LoadLibrariesResultFailure (loading error)
+    """
+
+
+@dataclass
+@PayloadRegistry.register
+class LoadLibrariesResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Libraries loaded successfully (or were already loaded)."""
+
+
+@dataclass
+@PayloadRegistry.register
+class LoadLibrariesResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Library loading failed. Common causes: library loading errors, configuration issues, initialization failures."""

griptape_nodes/retained_mode/events/os_events.py

@@ -52,10 +52,11 @@ class FileSystemEntry:
     """Represents a file or directory in the file system."""
 
     name: str
-    path: str
+    path: str  # Workspace-relative path (for portability)
     is_dir: bool
     size: int
     modified_time: float
+    absolute_path: str  # Absolute resolved path
     mime_type: str | None = None  # None for directories, mimetype for files
 
 
@@ -111,6 +112,8 @@ class ListDirectoryRequest(RequestPayload):
         show_hidden: Whether to show hidden files/folders
         workspace_only: If True, constrain to workspace directory. If False, allow system-wide browsing.
                         If None, workspace constraints don't apply (e.g., cloud environments).
+        pattern: Optional glob pattern to filter entries (e.g., "*.txt", "file_*.json").
+                 Only matches against file/directory names, not full paths.
 
     Results: ListDirectoryResultSuccess (with entries) | ListDirectoryResultFailure (access denied, not found)
     """
@@ -118,6 +121,7 @@ class ListDirectoryRequest(RequestPayload):
     directory_path: str | None = None
     show_hidden: bool = False
     workspace_only: bool | None = True
+    pattern: str | None = None
 
 
 @dataclass
@@ -474,3 +478,99 @@ class CopyFileResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
     """
 
     failure_reason: FileIOFailureReason
+
+
+@dataclass
+@PayloadRegistry.register
+class DeleteFileRequest(RequestPayload):
+    """Delete a file or directory.
+
+    Use when: Deleting files/directories through file picker,
+    implementing file deletion functionality, cleaning up temporary files.
+
+    Note: Directories are always deleted with all their contents.
+
+    Args:
+        path: Path to file/directory to delete (mutually exclusive with file_entry)
+        file_entry: FileSystemEntry from directory listing (mutually exclusive with path)
+        workspace_only: If True, constrain to workspace directory
+
+    Results: DeleteFileResultSuccess | DeleteFileResultFailure
+    """
+
+    path: str | None = None
+    file_entry: FileSystemEntry | None = None
+    workspace_only: bool | None = True
+
+
+@dataclass
+@PayloadRegistry.register
+class DeleteFileResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """File/directory deleted successfully.
+
+    Attributes:
+        deleted_path: The absolute path that was deleted (primary path)
+        was_directory: Whether the deleted item was a directory
+        deleted_paths: List of all paths that were deleted (for recursive deletes, includes all files/dirs)
+    """
+
+    deleted_path: str
+    was_directory: bool
+    deleted_paths: list[str]
+
+
+@dataclass
+@PayloadRegistry.register
+class DeleteFileResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """File/directory deletion failed.
+
+    Attributes:
+        failure_reason: Classification of why the deletion failed
+        result_details: Human-readable error message (inherited from ResultPayloadFailure)
+    """
+
+    failure_reason: FileIOFailureReason
+
+
+@dataclass
+@PayloadRegistry.register
+class GetFileInfoRequest(RequestPayload):
+    """Get information about a file or directory.
+
+    Use when: Checking if a path exists, determining if path is file/directory,
+    getting file metadata before operations.
+
+    Args:
+        path: Path to file/directory to get info about
+        workspace_only: If True, constrain to workspace directory
+
+    Results: GetFileInfoResultSuccess | GetFileInfoResultFailure
+    """
+
+    path: str
+    workspace_only: bool | None = True
+
+
+@dataclass
+@PayloadRegistry.register
+class GetFileInfoResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """File/directory either did not exist (we do not treat this as failure), or the info was retrieved successfully.
+
+    Attributes:
+        file_entry: FileSystemEntry with complete metadata, or None if the file/directory doesn't exist
+    """
+
+    file_entry: FileSystemEntry | None
+
+
+@dataclass
+@PayloadRegistry.register
+class GetFileInfoResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """File/directory info retrieval failed.
+
+    Attributes:
+        failure_reason: Classification of why retrieval failed
+        result_details: Human-readable error message (inherited from ResultPayloadFailure)
+    """
+
+    failure_reason: FileIOFailureReason