update

learning/04-TYPES_MESSAGES.md

@@ -248,6 +248,9 @@ struct ToolResultMessage <: Message
     is_error::Bool            # True if tool execution failed
     timestamp::Timestamp
 end
+
+# Note: AgentToolResult{T} (types.jl) - generic result type with type param T
+# AgentToolResultMutable (agent_loop.jl) - mutable variant used internally
 ```
 
 **Usage**:
@@ -288,6 +291,8 @@ end
 - `prepare_arguments`: Optional preprocessing
 - `execution_mode`: Sequential or parallel
 
+**Note:** `AgentHarnessTool` (`harness_types.jl:91`) is a harness-specific variant with the same structure but uses camelCase field names (`prepareArguments`, `executionMode`) and includes additional type parameters `{TContext, TParameters, TDetails}`.
+
 ### Tool Execution Function Signature
 
 ```julia
@@ -297,12 +302,12 @@ execute::Function(
     signal::Union{Any, Nothing},  # Abort signal
     on_update::Function,          # Callback for streaming updates
     context::Any,                 # Tool context
-)::AgentToolResult
+)::AgentToolResult{T}
 ```
 
-**Returns**:
+**Returns** (`AgentToolResult{T}` from `types.jl`):
 ```julia
-AgentToolResult(
+AgentToolResult{T}(
     content::Vector{MessageContent},  # Result content
     details::T,                       # Tool-specific details
     usage::Union{Usage, Nothing},     # Usage statistics
@@ -311,6 +316,10 @@ AgentToolResult(
 )
 ```
 
+**Note:** `AgentToolResultMutable` (in `agent_loop.jl`) is a mutable variant used internally for intermediate results.
+
+**Note:** External types used throughout the codebase: `Context`, `AbortSignal`, `EventStream`, `Promise` are defined in external modules (not in the source files covered by this document).
+
 ## AgentContext
 
 ```julia
@@ -532,6 +541,32 @@ mutable struct BranchSummaryMessage
 end
 ```
 
+### CustomMessage
+
+**Note:** There are two `CustomMessage` types in the codebase:
+
+1. **Types.CustomMessage** (`types.jl:155`) - A simple wrapper that holds another `AgentMessage` with a custom type label:
+```julia
+struct CustomMessage <: AgentMessage
+    message::AgentMessage
+    custom_type::String
+end
+```
+
+2. **Messages.CustomMessage{T}** (`messages.jl:42`) - A standalone mutable message with content, display flag, and details:
+```julia
+mutable struct CustomMessage{T}
+    role::String
+    custom_type::String
+    content::Union{String, Vector{MessageContent}}
+    display::Bool
+    details::Union{T, Nothing}
+    timestamp::Timestamp
+end
+```
+
+Only `Messages.CustomMessage{T}` is converted by `convertToLlmMessage()` to a `UserMessage`.
+
 ## AgentState
 
 ```julia
@@ -589,6 +624,8 @@ Vector{AgentMessage} (internal conversation history)
     │    (wrapped with COMPACTION_SUMMARY_PREFIX/SUFFIX)
     │  • BranchSummaryMessage → UserMessage
     │    (wrapped with BRANCH_SUMMARY_PREFIX/SUFFIX)
+    │  • CustomMessage → UserMessage
+    │    (content field used directly, string→TextContent)
     │
     ▼
 Vector{Message} (for LLM API)
@@ -607,6 +644,7 @@ Vector{Message} (for LLM API)
     ], "openai", "openai", "gpt-4", Usage(...), "done", nothing, 1234567891),
     BashExecutionMessage("custom", "ls -la", "file1.md\nfile2.md\n", 0, false, false, nothing, 1234567892, false),
     CompactionSummaryMessage("compactionSummary", "Previous conversation compacted", 1000, 1234567893),
+    CustomMessage("custom", "someCustomType", "Some custom content", true, nothing, 1234567894),
 ]
 
 # Output: Vector{Message}
@@ -618,6 +656,7 @@ Vector{Message} (for LLM API)
     ], "openai", "openai", "gpt-4", Usage(...), "done", nothing, 1234567891),
     UserMessage("user", [TextContent("Ran `ls -la`\n```\nfile1.md\nfile2.md\n```\n")], 1234567892),
     UserMessage("user", [TextContent("<summary>Previous conversation compacted</summary>")], 1234567893),
+    UserMessage("user", [TextContent("Some custom content")], 1234567894),
 ]
 ```
 
@@ -636,6 +675,15 @@ function convertToLlmMessage(m::CompactionSummaryMessage)
     return UserMessage("user", [TextContent(text)], m.timestamp)
 end
 
+function convertToLlmMessage(m::CustomMessage)::Union{UserMessage, Nothing}
+    content = if m.content isa String
+        [TextContent(m.content)]
+    else
+        m.content
+    end
+    return UserMessage("user", content, m.timestamp)
+end
+
 function convertToLlmMessage(m::BranchSummaryMessage)
     text = BRANCH_SUMMARY_PREFIX * m.summary * BRANCH_SUMMARY_SUFFIX
     return UserMessage("user", [TextContent(text)], m.timestamp)