update

static tool loading
2026-08-16 13:36:01 +07:00 · 2026-08-15 20:03:01 +07:00 · 2026-08-15 16:50:28 +07:00 · 2026-08-13 18:14:46 +07:00 · 2026-08-13 05:56:08 +07:00 · 2026-08-12 23:47:10 +07:00
22 changed files with 4054 additions and 1823 deletions
@@ -2,7 +2,7 @@

 julia_version = "1.12.6"
 manifest_format = "2.0"
-project_hash = "0db36d4fb31037ba05065476e6aebaf4cd0e1e8c"
+project_hash = "aa163e2bf572632825162936e107be18384fd40f"

 [[deps.Accessors]]
 deps = ["CompositionsBase", "ConstructionBase", "Dates", "InverseFunctions", "MacroTools"]
@@ -44,6 +44,12 @@ git-tree-sha1 = "d57bd3762d308bded22c3b82d033bff85f6195c6"
 uuid = "ec485272-7323-5ecc-a04f-4719b315124d"
 version = "0.4.0"

+[[deps.Arrow]]
+deps = ["ArrowTypes", "BitIntegers", "CodecLz4", "CodecZstd", "ConcurrentUtilities", "DataAPI", "Dates", "EnumX", "Mmap", "PooledArrays", "SentinelArrays", "StringViews", "Tables", "TimeZones", "TranscodingStreams", "UUIDs"]
+git-tree-sha1 = "4a69a3eadc1f7da78d950d1ef270c3a62c1f7e01"
+uuid = "69666777-d1a9-59fb-9406-91d4454c9d45"
+version = "2.8.1"
+
 [[deps.ArrowTypes]]
 deps = ["Sockets", "UUIDs"]
 git-tree-sha1 = "404265cd8128a2515a81d5eae16de90fdef05101"
@@ -58,6 +64,12 @@ version = "1.11.0"
 uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
 version = "1.11.0"

+[[deps.BitIntegers]]
+deps = ["Random"]
+git-tree-sha1 = "091d591a060e43df1dd35faab3ca284925c48e46"
+uuid = "c3b6d118-76ef-56ca-8cc7-ebb389d030a1"
+version = "0.3.7"
+
 [[deps.BufferedStreams]]
 git-tree-sha1 = "6863c5b7fc997eadcabdbaf6c5f201dc30032643"
 uuid = "e1450e63-4bb3-523b-b2a4-4ffa8c0fd77d"
@@ -90,12 +102,24 @@ git-tree-sha1 = "40956acdbef3d8c7cc38cba42b56034af8f8581a"
 uuid = "6c391c72-fb7b-5838-ba82-7cfb1bcfecbf"
 version = "0.3.4"

+[[deps.CodecLz4]]
+deps = ["Lz4_jll", "TranscodingStreams"]
+git-tree-sha1 = "d58afcd2833601636b48ee8cbeb2edcb086522c2"
+uuid = "5ba52731-8f18-5e0d-9241-30f10d1ec561"
+version = "0.4.6"
+
 [[deps.CodecZlib]]
 deps = ["TranscodingStreams", "Zlib_jll"]
 git-tree-sha1 = "962834c22b66e32aa10f7611c08c8ca4e20749a9"
 uuid = "944b1d66-785c-5afd-91f1-9de20f533193"
 version = "0.7.8"

+[[deps.CodecZstd]]
+deps = ["TranscodingStreams", "Zstd_jll"]
+git-tree-sha1 = "da54a6cd93c54950c15adf1d336cfd7d71f51a56"
+uuid = "6b39b394-51ab-5f42-8807-6242bab2b4c2"
+version = "0.8.7"
+
 [[deps.CommonSolve]]
 git-tree-sha1 = "cf963add2340ad9960e5eb22844e61ad8f931fe1"
 uuid = "38540f10-b2f7-11e9-35d8-d573e4eb0ff2"
@@ -130,6 +154,12 @@ weakdeps = ["InverseFunctions"]
    [deps.CompositionsBase.extensions]
    CompositionsBaseInverseFunctionsExt = "InverseFunctions"

+[[deps.ConcurrentUtilities]]
+deps = ["Serialization", "Sockets"]
+git-tree-sha1 = "3c9be947934c38475bafe822c6d61aaed17f0738"
+uuid = "f0e56b4a-5159-44fe-b623-3e5288b988bb"
+version = "2.6.0"
+
 [[deps.ConstructionBase]]
 git-tree-sha1 = "b4b092499347b18a015186eae3042f72267106cb"
 uuid = "187b0558-2788-49d3-abe0-74a17ed4e7c9"
@@ -531,6 +561,12 @@ git-tree-sha1 = "1d4c737ab26f51ceed52ab2019c09b7660eb7440"
 uuid = "6f1432cf-f94c-5a45-995e-cdbf5db27b0b"
 version = "3.8.0"

+[[deps.Lz4_jll]]
+deps = ["Artifacts", "JLLWrappers", "Libdl"]
+git-tree-sha1 = "191686b1ac1ea9c89fc52e996ad15d1d241d1e33"
+uuid = "5ced341a-0733-55b8-9ab6-a4889d929147"
+version = "1.10.1+0"
+
 [[deps.MacroTools]]
 git-tree-sha1 = "1e0228a030642014fe5cfe68c2c0a818f9e3f522"
 uuid = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09"
@@ -938,6 +974,11 @@ git-tree-sha1 = "8a90c1d77c3277a5d43b83927b3cbe2c70a37484"
 uuid = "892a3eda-7b42-436c-8928-eab12a02cf0e"
 version = "0.4.7"

+[[deps.StringViews]]
+git-tree-sha1 = "f2dcb92855b31ad92fe8f079d4f75ac57c93e4b8"
+uuid = "354b36f9-a18e-4713-926e-db85100087ba"
+version = "1.3.7"
+
 [[deps.StructTypes]]
 deps = ["Dates", "UUIDs"]
 git-tree-sha1 = "159331b30e94d7b11379037feeb9b690950cace8"
@@ -1080,6 +1121,14 @@ git-tree-sha1 = "011b0a7331b41c25524b64dc42afc9683ee89026"
 uuid = "a9144af2-ca23-56d9-984f-0d03f7b5ccf8"
 version = "1.0.21+0"

+[[deps.msghandler]]
+deps = ["Arrow", "Base64", "DataFrames", "Dates", "GeneralUtils", "HTTP", "JSON", "NATS", "PrettyPrinting", "Revise", "UUIDs"]
+git-tree-sha1 = "e82a79cf6602541ea25409aded57b2ace4a7c29f"
+repo-rev = "main"
+repo-url = "https://git.yiem.cc/ton/msghandler"
+uuid = "f2724d33-f338-4a57-b9f8-1be882570d10"
+version = "1.2.1"
+
 [[deps.nghttp2_jll]]
 deps = ["Artifacts", "Libdl"]
 uuid = "8e850ede-7688-5339-a07c-302acd2aaf8d"
@@ -22,6 +22,7 @@ SQLLLM = "2ebc79c7-cc10-4a3a-9665-d2e1d61e63d3"
 Serialization = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
 URIs = "5c2747f8-b7ea-4ff2-ba2e-563bfd36b1d4"
 UUIDs = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
+msghandler = "f2724d33-f338-4a57-b9f8-1be882570d10"

 [compat]
 Base64 = "1.11.0"
@@ -33,3 +34,4 @@ JSON = "1.6.1"
 LLMMCTS = "0.1.5"
 NATS = "0.1.0"
 SQLLLM = "0.2.8"
+msghandler = "1.2.1"
@@ -6,7 +6,7 @@ Julia framework for building agents with tool use.

 1. Install dependencies: `]add JSON, DataStructures, UUIDs, Dates, ...`
 2. Create a `yiemAgent` with `loadTools("src/tools")`
-3. Call `run_agent(agent, "message")` then `take_response(agent)`
+3. Call `runAgent(agent, "message")` then `takeResponse(agent)`

 ## Architecture

@@ -16,7 +16,7 @@ src/
 ├── type.jl               # Core types (messages, tools, agent state)
 ├── utils.jl              # Message formatting, validation
 ├── agentCore.jl          # Agent loop, tool execution pipeline
-├── api.jl                # Public API (run_agent, take_response, etc.)
+├── api.jl                # Public API (runAgent, takeResponse, etc.)
 └── tools/
    ├── registry.jl       # Tool registry (loadTools, registerTool, listTools)
    ├── getWeather.jl     # Weather lookup tool
@@ -1,2 +1,5 @@
-# ── executeToolCalls() Julia pseudo code ──────────────────────────
-# Full call stack from runLoop → executeToolCalls → prepare → execute → finalize → emit
+check my understand:
+1) if LLM didn't use tool calls, assistantMessage get pushed into agent._state.messages and 
+it will be the latest message in agent._state.messages. then _agentLoop() can pick it as 
+the output to outputChannel
+2) if LLM use tool calls but toolResultBatch.terminate is false, assistantMessageToolCall
@@ -0,0 +1,8 @@
+check my understanding
+1) if LLM didn't use tool calls, assistantMessage get pushed into agent._state.messages and it will be the latest message in agent._state.messages. then _agentLoop() can pick it as the output to outputChannel
+2) if LLM use tool calls, assistantMessageToolCall get pushed into agent._state.messages. then toolResult get pushed into agent._state.messages. if toolResultBatch.terminate is false then _processMessage() loop continue
+3) if LLM use tool calls, assistantMessageToolCall get pushed into agent._state.messages. then toolResult get pushed into agent._state.messages. if toolResultBatch.terminate is true then final_response message get pushed into agent._state.messages. _processMessage() loop exit. then _agentLoop() can pick it as the output to outputChannel
+
+Is my understanding correct?
+
+
@@ -1,7 +1,6 @@
 module YiemAgent

-  # export agent
-
+  export register_all_tools

  """ Order by dependencies of each file. The 1st included file must not depend on any other
  files and each file can only depend on the file included before it. 
@@ -13,9 +12,21 @@ module YiemAgent
  include("utils.jl")
  using .utils

-  include("tools/registry.jl")
+  include("tools/getWeather.jl")
+  include("tools/getTime.jl")
+  include("tools/writeTool.jl")
+
+  include("toolRegistry.jl")
  using .toolRegistry

+  function register_all_tools(store::toolRegistry.toolStore)
+      registerTool(store, getWeatherTool())
+      registerTool(store, getTimeTool())
+      registerTool(store, writeToolTool())
+      registerTool(store, listTool(store))
+      return store.tools
+  end
+
  # include("llmfunction.jl")
  # using .llmfunction

@@ -5,12 +5,11 @@ export prompt
 using JSON, DataStructures, Dates, UUIDs, HTTP, Random, PrettyPrinting, Serialization,
      DataFrames
 using GeneralUtils
-using ..type, ..utils
+using ..type, ..utils, ..agentCore, ..toolRegistry

 # ---------------------------------------------- 100 --------------------------------------------- #


-
 """
 Send a message to the agent's input channel.

@@ -25,16 +24,16 @@ The agent processes messages from `inputChannel` in the background task.
 - The same `agent` instance for chaining

 # Notes
- Use `take_response(agent)` to receive the agent's response after sending a message.
- Use `follow_up(agent, msg)` to send messages while the agent is still processing.
+- Use `takeResponse(agent)` to receive the agent's response after sending a message.
+- Use `followUp(agent, msg)` to send messages while the agent is still processing.

 # Examples
 ```jldoctest
-julia> run_agent(agent, "Hello!")
+julia> runAgent(agent, "Hello!")
 yiemAgent(...)
 ```
 """
-function run_agent(agent::yiemAgent, msg)
+function runAgent(agent::yiemAgent, msg)
  put!(agent.inputChannel, msg)
  return agent
 end
@@ -51,15 +50,15 @@ Blocks until the agent sends a response.
 - An `assistantMessage` instance representing the agent's response

 # Notes
- Use `run_agent(agent, msg)` to send a message before calling this function.
+- Use `runAgent(agent, msg)` to send a message before calling this function.

 # Examples
 ```jldoctest
-julia> response = take_response(agent)
+julia> response = takeResponse(agent)
 assistantMessage(...)
 ```
 """
-function take_response(agent::yiemAgent)
+function takeResponse(agent::yiemAgent)
  return take!(agent.outputChannel)
 end

@@ -77,17 +76,17 @@ and before any tool call results are sent.
 - The same `agent` instance for chaining

 # Notes
- Use `run_agent(agent, msg)` for the primary message and `follow_up(agent, msg)` for additional
+- Use `runAgent(agent, msg)` for the primary message and `followUp(agent, msg)` for additional
  messages while the agent is processing.
 - Follow-up messages are buffered in a separate channel (capacity 32 by default).

 # Examples
 ```jldoctest
-julia> follow_up(agent, "Also consider red wines")
+julia> followUp(agent, "Also consider red wines")
 yiemAgent(...)
 ```
 """
-function follow_up(agent::yiemAgent, msg)
+function followUp(agent::yiemAgent, msg)
  put!(agent.followUpChannel, msg)
  return agent
 end
@@ -105,19 +104,19 @@ then closes all channels (`inputChannel`, `outputChannel`, `followUpChannel`).
 - `nothing`

 # Notes
- After calling `stop_agent`, the agent is no longer usable. A new agent must be created
+- After calling `stopAgent`, the agent is no longer usable. A new agent must be created
  for further interaction.
 - If the background task throws a `TaskFailedException`, it is rethrown.

 # Examples
 ```jldoctest
-julia> stop_agent(agent)
+julia> stopAgent(agent)
 ```
 """
-function stop_agent(agent::yiemAgent)
+function stopAgent(agent::yiemAgent)
  put!(agent.inputChannel, :shutdown)
  try
-    fetch(agent._agent_loop)
+    fetch(agent._agentLoop)
  catch e
    if e isa TaskFailedException
      rethrow(e)
@@ -0,0 +1,179 @@
+module toolRegistry
+
+export toolStore, registerTool, getTools, clearTools, listTool
+
+using Dates
+using JSON, DataStructures
+using ..type
+
+"""
+Per-agent isolated tool storage.
+
+Each agent gets its own `toolStore` so tool registration is independent —
+`registerTool(store, tool)` only affects that agent's tool set.
+
+# Fields
+- `tools::OrderedDict{String, agentTool}` — keyed by name for O(1) lookup + ordered iteration
+- `name::String` — identifier for debugging/logs
+"""
+struct toolStore
+    tools::OrderedDict{String, agentTool}
+    name::String
+end
+
+"""
+    toolStore(; name="default") -> toolStore
+
+Create a new empty tool store.
+
+# Keyword Arguments
+- `name::String`: Display name for logging (default: `"default"`)
+
+# Example
+```julia
+julia> store = toolStore(name="agent1")
+toolStore(OrderedDict{String, agentTool}(), "agent1")
+```
+"""
+function toolStore(; name::String="default")::toolStore
+    toolStore(OrderedDict{String, agentTool}(), name)
+end
+
+"""
+    listTool(store::toolStore) -> agentTool
+
+Return an `agentTool` definition for listing registered tools.
+
+Each call produces a **new** tool object that captures (closes over)
+`store`. `register_all_tools` auto-registers one so the LLM can discover tools
+at runtime.
+
+# Arguments
+- `store`: The tool store whose tools will be listed when the tool runs
+
+# Example
+```julia
+julia> store = toolStore(name="agent1");
+
+julia> register_all_tools(store)  # auto-registers listTools
+[toolRegistry:agent1] Loaded tool: getWeather (Weather Lookup)
+[toolRegistry:agent1] Registered tool: listTools
+
+julia> tools = getTools(store)
+OrderedDict{String, agentTool} with 4 entries:
+  "getWeather" => agentTool(...)
+  "getTime" => agentTool(...)
+  "writeTool" => agentTool(...)
+  "listTools" => agentTool(...)
+```
+"""
+function listTool(store::toolStore)::agentTool
+    return agentTool(
+        name = "listTools",
+        label = "List Tools",
+        description = "List all available tools with their names, labels, and descriptions. Use this before creating a new tool to check for name collisions.",
+        inputSchema = Dict{String,Any}(
+            "type" => "object",
+            "properties" => Dict{String,Any}(),
+            "required" => Any[]
+        ),
+        execute = (toolCallId, args, signal, onPartialResult) -> begin
+            tools = getTools(store)
+            if isempty(tools)
+                result_text = "No tools registered."
+            else
+                lines = String["- $(t.name): $(t.label) — $(t.description)" for (k, t) in tools]
+                result_text = "Available tools:\n" * join(lines, "\n")
+            end
+            return agentToolResult(
+                [textContent(result_text)],
+                Dict{Any,Any}("count" => length(tools)),
+                nothing, false
+            )
+        end,
+        prepareArguments = nothing,
+        validateRequiredArgs = nothing,
+        parallelToolExecute = false
+    )
+end
+
+# Note: register_all_tools is defined in YiemAgent.jl where tool functions are in scope
+
+"""
+    registerTool(store::toolStore, tool::agentTool) -> OrderedDict{String, agentTool}
+
+Add `tool` to `store`, overwriting any existing tool with the same name.
+
+# Arguments
+- `store`: Tool store to modify
+- `tool`: The `agentTool` to register
+
+# Returns
+- The same `store.tools` dict (modified in place)
+
+# Example
+```julia
+julia> store = toolStore(name="agent1");
+
+julia> registerTool(store, listTool(store))
+[toolRegistry:agent1] Registered tool: listTools
+OrderedDict{String, agentTool} with 1 entry:
+  "listTools" => agentTool(...)
+```
+"""
+function registerTool(store::toolStore, tool::agentTool)::OrderedDict{String, agentTool}
+    store.tools[tool.name] = tool
+    println("[$(store.name)] Registered tool: $(tool.name)")
+    return store.tools
+end
+
+"""
+Return the tools registered in `store`.
+
+The returned dict is the **same object** stored inside `store` — mutations
+to it (e.g. via `registerTool`) are visible through subsequent calls.
+
+# Arguments
+- `store`: Tool store to query
+
+# Returns
+- `OrderedDict{String, agentTool}`: Tools keyed by name, in registration order
+
+# Example
+```julia
+julia> tools = getTools(store)
+OrderedDict{String, agentTool} with 2 entries:
+  "getWeather" => agentTool(...)
+  "getTime" => agentTool(...)
+```
+"""
+function getTools(store::toolStore)::OrderedDict{String, agentTool}
+    return store.tools
+end
+
+"""
+Remove all tools from `store`.
+
+# Arguments
+- `store`: Tool store to clear
+
+# Returns
+- `nothing`
+
+# Example
+```julia
+julia> clearTools(store)
+[toolRegistry:agent1] Registry cleared
+nothing
+
+julia> getTools(store)
+OrderedDict{String, agentTool} with 0 entries
+```
+"""
+function clearTools(store::toolStore)::Nothing
+    empty!(store.tools)
+    println("[$(store.name)] Registry cleared")
+    return nothing
+end
+
+end # module
@@ -1,525 +0,0 @@
-# Tools
-
-Tools allow the agent to perform actions and fetch data. Each tool defines a **schema** (what arguments it accepts) and an **execution function** (what it does).
-
-## Tool Anatomy
-
-Each tool has 3 main parts:
-
-### 1. Schema (`inputSchema`)
-
-JSON Schema (MCP format) describing the tool's arguments. The `"required"` array lists mandatory fields:
-
-```julia
-inputSchema = Dict{String,Any}(
-    "type" => "object",
-    "properties" => Dict(
-        "city" => Dict("type" => "string", "description" => "City name"),
-        "units" => Dict("type" => "string", "enum" => ["celsius", "fahrenheit"], "default" => "celsius")
-    ),
-    "required" => ["city"]
-)
-```
-
-### 2. Execution Function (`execute`)
-
-A function with the signature:
-
-```julia
-execute(toolCallId::String, args::Dict{String,Any}, signal::Union{Nothing,abortSignal}, onPartialResult::Function)::agentToolResult
-```
-
- **`toolCallId`** — unique ID for this invocation (from the LLM's tool call)
- **`args`** — validated arguments provided by the LLM
- **`signal`** — abort signal for cancellable operations
- **`onPartialResult`** — callback for streaming progress updates
- **Returns** — `agentToolResult` with content, details, usage, and termination flag
-
-```julia
-function executeTool(toolCallId::String, args::Dict{String,Any}, signal::Union{Nothing,abortSignal}, onPartialResult::Function)::agentToolResult
-    # Optional: stream progress updates
-    onPartialResult(Dict("status" => "Fetching data..."))
-    
-    # Do work
-    result = "Weather in $(args["city"]): Sunny, 22°C"
-    
-    # Return result
-    return agentToolResult(
-        [textContent(result)],
-        Dict{Any,Any}(),  # details
-        nothing,           # usage
-        false              # terminate (true to stop agent loop)
-    )
-end
-```
-
-### 3. Tool Definition (`getTool()`)
-
-Returns an `agentTool` struct:
-
-| Field | Type | Description |
-|---|---|---|
-| `name` | `String` | Unique identifier (e.g. `"getWeather"`) |
-| `label` | `String` | Human-readable name (e.g. `"Weather Lookup"`) |
-| `description` | `String` | What the tool does (shown to the LLM) |
-| `inputSchema` | `Any` | JSON Schema (MCP format) |
-| `execute` | `Function` | The execution function |
-| `prepareArguments` | `Union{Function,Nothing}` | Optional argument transform before validation |
-| `validateRequiredArgs` | `Union{Function,Nothing}` | Optional custom validation |
-| `parallelToolExecute` | `Bool` | Run this tool in parallel with others |
-
-## Argument Validation
-
-Validation happens **before** tool execution, in the `prepareToolCall` phase. Invalid calls return an error immediately without invoking `execute`, `beforeToolCall`, or logging `toolExecutionStart`.
-
-### Default: JSON Schema Required Fields
-
-Set `validateRequiredArgs = nothing` to use the default validator, which checks that all fields in `inputSchema["required"]` are present:
-
-```julia
-# src/tools/getWeather.jl — uses default validation
-function getTool()::agentTool
-    return agentTool(
-        name = "getWeather",
-        # ...
-        validateRequiredArgs = nothing,  # uses default
-    )
-end
-```
-
-### Custom Validation Hook
-
-Override `validateRequiredArgs` when you need:
- **Cross-field constraints** (e.g. "at least one of X or Y")
- **Format validation** (e.g. regex patterns, date parsing)
- **Domain rules** (e.g. value ranges, business logic)
-
-The hook signature takes only `args`:
-
-```julia
-function validateRequiredArgs(args::Dict{String,Any})::Union{Nothing,String}
-    tz = get(args, "timezone", nothing)
-    city = get(args, "city", "")
-    
-    if !haskey(args, "timezone") && isempty(city)
-        return "Missing required argument: provide at least one of 'timezone' or 'city'"
-    end
-    
-    if tz !== nothing
-        tz_str = string(tz)
-        if !occursin(r"^[A-Za-z]+\/[A-Za-z]+(/[A-Za-z]+)*$", tz_str)
-            return "Invalid timezone format: '$tz_str'. Use IANA format, e.g. 'America/New_York'"
-        end
-    end
-    
-    return nothing
-end
-```
-
-Return `nothing` to pass, or an error `String` to fail. The error is fed back to the LLM so it can retry with corrected arguments.
-
-## Tool Discovery and Lifecycle
-
-The agent iterates through tools via a **discover → execute → loop** cycle. Here is the complete flow from the framework author's perspective:
-
-### The Agent Loop
-
-```julia
-# agentCore.jl:175 - _process_message()
-while true
-    # 1. Drain messages from inputChannel
-    while isready(agent.inputChannel)
-        raw_msg = take!(agent.inputChannel)
-        user_msg = OpenAiToUserMessage(raw_msg)
-        push!(agent._state.messages, user_msg)
-    end
-
-    # 2. Format messages for LLM
-    ctx = agent.prepareContext(agent._state)
-    formatted = agent.formatMsgForLLM(ctx)
-
-    # 3. Call LLM
-    response = agent.llmCall(formatted)
-
-    # 4. Check if LLM used tool calls
-    if has_tool_calls(response.content)
-        # 5. Execute tools, feed results back to LLM, loop
-    else
-        # 6. No tool calls — return final response
-        break
-    end
-end
-```
-
-### Step 1: Tool Discovery
-
-Tools are discovered from `agent._state.tools`, which is a `Vector{agentTool}` populated during agent creation:
-
-```julia
-# Loading tools
-tools = loadTools("src/tools")  # returns Vector{agentTool}
-
-# Passing to agent
-agent = yiemAgent(
-    systemPrompt = "...",
-    tools = tools,  # ← tools stored in agent._state.tools
-    llmCall = my_llm_call,
-    agentEventSink = my_event_sink,
-)
-```
-
-When the LLM response contains tool calls, the agent builds an `agentContext` with those tools:
-
-```julia
-context = agentContext(
-    agent._state.systemPrompt,
-    agent._state.messages,
-    agent._state.tools,  # ← tools available for discovery
-)
-```
-
-### Step 2: Extract Tool Calls from LLM Response
-
-The agent inspects the `response.content` blocks for `tool_calls`:
-
-```julia
-# agentCore.jl:217-245
-tool_call_list = agentToolCall[]
-
-for content_block in response.content
-    if content_block isa Dict
-        if get(content_block, :type, "") == "tool_calls"
-            # OpenAI format: {"type": "tool_calls", "tool_calls": [...]}
-            for tc_data in get(content_block, :tool_calls, [])
-                tc = agentToolCall(
-                    type = "function",
-                    id = get(tc_data, :id, string(uuid4())),
-                    name = get(tc_data, :function, Dict())[:name],
-                    arguments = get(tc_data, :function, Dict())[:arguments],
-                )
-                push!(tool_call_list, tc)
-            end
-        elseif get(content_block, :type, "") == "tool_call"
-            # Alternative format: single tool_call block
-            tc = agentToolCall(
-                type = "function",
-                id = get(content_block, :id, string(uuid4())),
-                name = get(content_block, :name, ""),
-                arguments = get(content_block, :arguments, Dict()),
-            )
-            push!(tool_call_list, tc)
-        end
-    end
-end
-```
-
-### Step 3: Execute Each Tool Call
-
-For each tool call, the agent runs through the **prepare → execute → finalize** pipeline:
-
-```julia
-# agentCore.jl:247-302
-if has_tool_calls && length(tool_call_list) > 0
-    context = agentContext(agent._state.systemPrompt, agent._state.messages, agent._state.tools)
-    config = agentLoopConfig(agent._state.tools, agent.beforeToolCall, agent.afterToolCall, execution_mode)
-    signal = nothing
-    emit = agent.agentEventSink
-
-    # Execute all tool calls (sequential or parallel)
-    batch = executeToolCalls(context, response, tool_call_list, config, signal, emit)
-
-    # Save results to conversation history
-    for tool_result in batch.messages
-        push!(agent._state.messages, tool_result)
-    end
-
-    # If any tool requested termination, break the loop
-    if batch.terminate
-        final_response = build_final_response(batch)
-        break
-    end
-    # Otherwise, loop back to step 2 (format + call LLM again)
-end
-```
-
-### Step 4: The Per-Call Pipeline
-
-Each tool call goes through three phases:
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ PREPARE  →  prepareToolCall()                                  │
-│                                                                 │
-│   1. Find tool by name in context.tools                         │
-│   2. Transform args via tool.prepareArguments (if defined)      │
-│   3. Validate via tool.validateRequiredArgs (or default)        │
-│   4. Run beforeToolCall hook (if defined)                       │
-│   └── on any failure → return immediateOutcome (skip execution) │
-│   └── success → return preparedToolCall                         │
-├─────────────────────────────────────────────────────────────────┤
-│ EXECUTE  →  executePreparedToolCall()                           │
-│                                                                 │
-│   1. emit toolExecutionStart event                              │
-│   2. call tool.execute(toolCallId, args, signal, onPartialResult)│
-│   3. wait for all pending update events                         │
-│   └── on error → return executedOutcome(isError=true)           │
-│   └── success → return executedOutcome(isError=false)           │
-├─────────────────────────────────────────────────────────────────┤
-│ FINALIZE  →  finalizeExecutedToolCall()                         │
-│                                                                 │
-│   1. Run afterToolCall hook (if defined)                        │
-│      - can mutate content, details, usage, terminate, isError   │
-│   2. emit toolExecutionEnd event                                │
-│   3. createToolResultMessage → adds to conversation history     │
-│   └── return finalizedOutcome                                   │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Step 5: Feed Results Back to LLM
-
-Tool results are added to `agent._state.messages` as `toolResultMessage` objects. On the next loop iteration, `formatMsgForLLM()` converts them to OpenAI format and the LLM receives the results:
-
-```
-Conversation history after tool execution:
-  [system] "You are a helpful assistant."
-  [user] "What's the weather in Tokyo?"
-  [assistant] (tool_calls: getWeather(city="Tokyo"))
-  [tool] tool_call_id="call_1", tool_name="getWeather", content="Weather in Tokyo: Sunny, 22°C"
-```
-
-The LLM then decides: call another tool, or return a final text answer.
-
-## Execution Modes
-
-### Sequential
-
-Tools execute one at a time in order. Required when:
- Tools have implicit dependencies
- Tools share state (e.g. writing to the same file)
- Tools have `parallelToolExecute = false`
-
-Set globally via `agentLoopConfig.toolExecution = "sequential"`, or per-tool via `parallelToolExecute = false`.
-
-### Parallel
-
-Tools execute concurrently when all are independent. Reduces wall-clock time. Set `parallelToolExecute = true` on individual tools, or set `agentLoopConfig.toolExecution = "parallel"`.
-
-## Streaming Partial Results
-
-For long-running tools (API calls, file uploads, training), use `onPartialResult` to stream progress:
-
-```julia
-function executeTool(toolCallId::String, args::Dict{String,Any}, signal::Union{Nothing,abortSignal}, onPartialResult::Function)::agentToolResult
-    onPartialResult(Dict("status" => "Step 1: Fetching data..."))
-    sleep(1)
-    
-    onPartialResult(Dict("status" => "Step 2: Processing..."))
-    sleep(1)
-    
-    return agentToolResult(
-        [textContent("Done!")],
-        Dict{Any,Any}(), nothing, false
-    )
-end
-```
-
-UI listeners and the TUI consume these events in real time via `toolExecutionUpdate`.
-
-## Loading Tools
-
-### Auto-load from Directory
-
-```julia
-using .toolRegistry
-
-tools = loadTools("src/tools")  # scans for *.jl files with getTool()
-```
-
-Files are loaded alphabetically for deterministic registration order.
-
-### Manual Registration
-
-```julia
-tool = getTool()  # from your tool module
-registerTool(tool)
-```
-
-## Complete Lifecycle Example
-
-```julia
-# ─── USER SENDS MESSAGE ───────────────────────────────────────────
-run_agent(agent, "What's the weather in Tokyo?")
-
-# ─── LOOP ITERATION 1 ─────────────────────────────────────────────
-# Agent formats messages and calls LLM
-formatted = agent.formatMsgForLLM(agent.prepareContext(agent._state))
-response = agent.llmCall(formatted)
-# LLM returns: {"content": [{"type": "tool_calls", "tool_calls": [{"name": "getWeather", "arguments": {"city": "Tokyo"}}]}]}
-
-# Agent extracts tool call, builds context
-context = agentContext(systemPrompt, messages, agent._state.tools)
-tool_call_list = [agentToolCall("call_1", "getWeather", Dict("city" => "Tokyo"))]
-
-# PREPARE: find tool, validate args
-tool = find(t -> t.name == "getWeather", context.tools)  # found!
-validateRequiredArgs(Dict("city" => "Tokyo"), tool.inputSchema)  # passes
-beforeToolCall_hook(agentMsgCtx, nothing)  # nil, skipped
-
-# EXECUTE: call tool.execute()
-result = tool.execute("call_1", Dict("city" => "Tokyo"), nothing, onPartialResult)
-# Returns: agentToolResult([textContent("Weather in Tokyo: Sunny, 22°C")], Dict(), nothing, false)
-
-# FINALIZE: afterToolCall hook, emit events
-finalized = finalizedOutcome(tc, result, false)
-emit(toolExecEndEvent("call_1", "getWeather", result, false))
-msg = createToolResultMessage(finalized)  # toolResultMessage for conversation history
-
-# Add result to conversation
-push!(agent._state.messages, msg)
-# Messages now: [user: "What's the weather?", assistant: {tool_calls: getWeather}, tool: "Sunny, 22°C"]
-
-# ─── LOOP ITERATION 2 ─────────────────────────────────────────────
-# LLM called again with tool result included
-formatted = agent.formatMsgForLLM(agent.prepareContext(agent._state))
-response = agent.llmCall(formatted)
-# LLM returns: {"content": [{"type": "text", "text": "The weather in Tokyo is sunny, 22°C."}]}
-
-# No tool calls detected → break loop, return final response
-return assistantMessage(content=[textContent("The weather in Tokyo is sunny, 22°C.")], ...)
-
-# ─── USER RECEIVES RESPONSE ───────────────────────────────────────
-response = take_response(agent)
-println(response.content)
-# => "[textContent(\"The weather in Tokyo is sunny, 22°C.\")]"
-```
-
-## Self-Modifying Tools
-
-The framework includes tools that allow the agent to create new tools at runtime.
-
-### `writeTool` — Create New Tool Files
-
-`writeTool` is a **file writer**, not a code generator. The LLM provides the tool logic as `executeCode` (the actual Julia code), and `writeTool` wraps it in the required boilerplate.
-
-**How it works:**
-
-The LLM constructs `writeTool` with:
- **`executeCode`** — the actual tool logic (Julia code body, NOT wrapped in a function)
- **`name`, `label`, `description`** — tool metadata
- **`inputSchema`** — parameter schema in MCP format
- **`validateCode`, `prepareCode`** (optional) — custom validation/preparation logic
-
-`writeTool` produces `src/tools/<name>.jl` by:
-1. Converting the `inputSchema` Dict into a Julia `Dict{String,Any}(...)` string literal
-2. Indenting `executeCode` with 4 spaces
-3. Wrapping it inside a `function executeTool(...)::agentToolResult ... end` template
-4. Appending the `getTool()` definition that returns an `agentTool` struct
-5. Writing the combined string to disk
-
-**Workflow:**
-
-```
-LLM decides: "Need a searchWine tool. I'll provide the logic."
-
-LLM calls writeTool:
-  name: "searchWine"
-  executeCode: "query = args[\"query\"]\nresult = search(query)\nreturn ..."
-
-writeTool wraps it → src/tools/searchWine.jl:
-  function executeTool(...)::agentToolResult
-      query = args["query"]          ← LLM code (indented 4 spaces)
-      result = search(query)
-      return agentToolResult(...)
-  end
-
-  function getTool()::agentTool
-      return agentTool(name="searchWine", ...)
-  end
-
-Restart → loadTools("src/tools") loads searchWine.jl
-```
-
-**Example specification:**
-
-```julia
-Dict(
-    "name" => "searchWine",
-    "label" => "Wine Search",
-    "description" => "Search a wine database by name, region, or variety",
-    "inputSchema" => Dict(
-        "type" => "object",
-        "properties" => Dict(
-            "query" => Dict("type" => "string", "description" => "Search query"),
-            "maxResults" => Dict("type" => "integer", "default" => 10)
-        ),
-        "required" => ["query"]
-    ),
-    "executeCode" => """
-        query = args["query"]
-        max_results = get(args, "maxResults", 10)
-        # Perform search logic here
-        result = "Found 3 wines matching: $query"
-        return agentToolResult([textContent(result)], Dict{Any,Any}(), nothing, false)
-    """,
-    "parallel" => false
-)
-```
-
-**Optional hooks:**
-
-| Field | Description |
-|---|---|
-| `validateCode` | Custom validation Julia code (runs before execute). Return `nothing` to pass, or an error `String` to fail. |
-| `prepareCode` | Argument preparation code (runs before validation). Return modified args dict. |
-
-### `listTools` — Discover Available Tools
-
-Returns all registered tools. Primarily useful for **collision detection** before creating a new tool via `writeTool` — the LLM checks existing names before picking a unique one.
-
-```julia
-# Result from listTools:
-# Available tools:
-# - getWeather: Weather Lookup — Fetch current weather and forecast for a given city.
-# - getTime: Time Lookup — Get current local time for a timezone or city.
-# - writeTool: Create Tool — Generate new tool files...
-# - listTools: List Tools — List all available tools with their names and labels...
-```
-
-### Complete Self-Tooling Example
-
-```
-User: "I need to search for wines. Do you have a tool for that?"
-
-# ─── LOOP: Agent realizes no wine search tool exists ─────────────────
-
-# LLM generates the tool logic and calls writeTool to write it to disk
-
-[Tool Call] writeTool(name="searchWine", label="Wine Search",
-    description="Search a wine database by name, region, or variety",
-    inputSchema={...},
-    executeCode="query = args[\"query\"]\nresult = \"Found wines...\"\nreturn agentToolResult([textContent(result)], ...)")
-
-# writeTool generates src/tools/searchWine.jl
-
-# ─── SYSTEM RESTARTS ─────────────────────────────────────────────────
-
-# loadTools("src/tools") loads searchWine.jl alongside all other tools
-
-# ─── Agent calls the new tool ─────────────────────────────────────────
-
-[Tool Call] searchWine(query="cabernet", maxResults=5)
-# Result: "Found 5 cabernet wines..."
-
-# ─── Final response ──────────────────────────────────────────────────
-
-"The search found 5 cabernet wines: ..."
-```
-
-## Available Tools
-
-| Tool | Description | Validation |
-|---|---|---|
-| `getWeather` | Fetch weather for a city | Default (JSON Schema required) |
-| `getTime` | Get current time for a timezone or city | Custom (cross-field + format) |
-| `writeTool` | Create a new Julia tool module at runtime | Built-in (name + schema validation) |
-| `listTools` | List all available tools with descriptions | None (no arguments) |
@@ -1,3 +1,6 @@
+using .type
+using Dates
+
 """
 Validate required arguments for the getTime tool.

@@ -13,7 +16,7 @@ Demonstrates custom validation beyond simple required-field checking:
 - `nothing` if validation passes
 - `String` error message if validation fails
 """
-function validateRequiredArgs(args::Dict{String,Any})::Union{Nothing,String}
+function getTimeValidateRequiredArgs(args::Dict{String,Any})::Union{Nothing,String}
    tz = get(args, "timezone", nothing)
    city = get(args, "city", "")
    
@@ -36,10 +39,30 @@ function validateRequiredArgs(args::Dict{String,Any})::Union{Nothing,String}
    return nothing
 end

+"""
+Execute the getTime tool.
+
+Returns mock time data for the given timezone or city.
+"""
+function getTimeExecute(toolCallId::String, args::Dict{String,Any}, signal::Union{Nothing,abortSignal},
+  onPartialResult)
+    tz = get(args, "timezone", nothing)
+    city = get(args, "city", "")
+    if tz !== nothing
+        result = "Current time in $(tz): $(now())"
+    else
+        result = "Current time in $(city): $(now())"
+    end
+    return agentToolResult(
+        [textContent(result)],
+        Dict{Any,Any}(), nothing, false
+    )
+end
+
 """
 Define and return the getTime agentTool.
 """
-function getTool()::agentTool
+function getTimeTool()::agentTool
    return agentTool(
        name = "getTime",
        label = "Time Lookup",
@@ -52,21 +75,9 @@ function getTool()::agentTool
            ),
            "required" => []
        ),
-        execute = (toolCallId, args, signal, onPartialResult) -> begin
-            tz = get(args, "timezone", nothing)
-            city = get(args, "city", "")
-            if tz !== nothing
-                result = "Current time in $(tz): $(now())"
-            else
-                result = "Current time in $(city): $(now())"
-            end
-            return agentToolResult(
-                [textContent(result)],
-                Dict{Any,Any}(), nothing, false
-            )
-        end,
+        execute = getTimeExecute,
        prepareArguments = nothing,
-        validateRequiredArgs = validateRequiredArgs,
+        validateRequiredArgs = getTimeValidateRequiredArgs,
        parallelToolExecute = false
    )
 end
@@ -1,7 +1,33 @@
+using msghandler
+using .type
+
+"""
+Execute the getWeather tool.
+
+Returns mock weather data for the given city and temperature units.
+"""
+function getWeatherExecute(toolCallId::String, args::Dict{String,Any}, signal::Union{Nothing,abortSignal},
+  agentEventSink)
+
+  agentEventSink("Getting weather...")
+
+  city = get(args, "city", "")
+  units = get(args, "units", "celsius")
+  temp = units == "fahrenheit" ? "72" : "22"
+  unit_symbol = units == "celsius" ? "°C" : "°F"
+  
+  return agentToolResult(
+      [textContent("Weather in $(city): Sunny, $(temp)$(unit_symbol)")],
+      Dict{Any,Any}(), 
+      nothing, 
+      false
+    )
+end
+
 """
 Define and return the getWeather agentTool.
 """
-function getTool()::agentTool
+function getWeatherTool()::agentTool
    return agentTool(
        name = "getWeather",
        label = "Weather Lookup",
@@ -14,16 +40,7 @@ function getTool()::agentTool
            ),
            "required" => ["city"]
        ),
-        execute = (toolCallId, args, signal, onPartialResult) -> begin
-            city = get(args, "city", "")
-            units = get(args, "units", "celsius")
-            temp = units == "fahrenheit" ? "72" : "22"
-            unit_symbol = units == "celsius" ? "°C" : "°F"
-            return agentToolResult(
-                [textContent("Weather in $(city): Sunny, $(temp)$(unit_symbol)")],
-                Dict{Any,Any}(), nothing, false
-            )
-        end,
+        execute = getWeatherExecute,
        prepareArguments = nothing,
        validateRequiredArgs = nothing,
        parallelToolExecute = false
@@ -1,174 +0,0 @@
-module toolRegistry
-
-export loadTools, registerTool, getTools, clearTools
-
-using Dates
-using JSON
-using ..type
-
-# Global registry — populated at runtime by loadTools() or registerTool()
-const _registry = Vector{agentTool}()
-
-# Auto-register the built-in listTools tool
-function __init__()
-    registerTool(_listTool())
-end
-
-"""
-List tool definition — lets the agent query available tools for collision detection
-when creating new tools via writeTool.
-"""
-function _listTool()::agentTool
-    return agentTool(
-        name = "listTools",
-        label = "List Tools",
-        description = "List all available tools with their names, labels, and descriptions. Use this before creating a new tool to check for name collisions.",
-        inputSchema = Dict{String,Any}(
-            "type" => "object",
-            "properties" => Dict{String,Any}(),
-            "required" => Any[]
-        ),
-        execute = (toolCallId, args, signal, onPartialResult) -> begin
-            tools = getTools()
-            if isempty(tools)
-                result_text = "No tools registered."
-            else
-                lines = String["- $(t.name): $(t.label) — $(t.description)" for t in tools]
-                result_text = "Available tools:\n" * join(lines, "\n")
-            end
-            return agentToolResult(
-                [textContent(result_text)],
-                Dict{Any,Any}("count" => length(tools)),
-                nothing, false
-            )
-        end,
-        prepareArguments = nothing,
-        validateRequiredArgs = nothing,
-        parallelToolExecute = false
-    )
-end
-
-"""
-Load all tool modules from a directory.
-
-Scans `dir` for `.jl` files. Each file must define a function named
-`getTool()::agentTool`.  Files are sorted alphabetically so tool
-registration order is deterministic.
-
-# Tool file format
-Each `.jl` file defines one function `getTool()` that returns an `agentTool`:
-
-```julia
-# src/tools/getWeather.jl
-function getTool()::agentTool
-    return agentTool(
-        name = "getWeather",
-        label = "Weather Lookup",
-        description = "Fetch current weather and forecast for a given city.",
-        inputSchema = Dict{String,Any}(
-            "type" => "object",
-            "properties" => Dict(
-                "city" => Dict("type" => "string", "description" => "City and country"),
-                "units" => Dict("type" => "string", "enum" => ["celsius", "fahrenheit"], "default" => "celsius")
-            ),
-            "required" => ["city"]
-        ),
-        execute = (toolCallId, args, signal, onPartialResult) -> begin
-            city = args["city"]
-            return agentToolResult(
-                [textContent("Sunny, 22C in Bangkok")],
-                Dict{Any,Any}(), nothing, false
-            )
-        end,
-        prepareArguments = nothing,
-        parallelToolExecute = false
-    )
-end
-```
-
-# Arguments
- `dir::String`: Directory path to scan for `.jl` tool files
-
-# Returns
- `Vector{agentTool}`: All loaded tools
-
-# Errors
- Throws `ArgumentError` if a tool file does not define a `getTool` function
-"""
-function loadTools(dir::String)::Vector{agentTool}
-    if !isdir(dir)
-        throw(ArgumentError("Tool directory does not exist: $dir"))
-    end
-
-    tools = agentTool[]
-    jl_files = filter(f -> endswith(f, ".jl") && !occursin(r"(?i)registry", f), readdir(dir))
-    sort!(jl_files)
-
-    for filename in jl_files
-        filepath = joinpath(dir, filename)
-        println("[toolRegistry] Loading tool from: $filepath")
-
-        # Include the file in the current module scope so all types resolve
-        # (agentTool, textContent, agentToolResult, etc. are all available)
-        include(filepath)
-
-        # Validate that getTool was defined (include() places it in current module scope)
-        if !isdefined(@__MODULE__, :getTool)
-            throw(ArgumentError(
-                "Tool file $(filepath) does not define a `getTool()` function. " *
-                "Each tool file must define: function getTool()::agentTool ... end"
-            ))
-        end
-
-        # Call getTool() — it runs in current scope where types are visible
-        # Use invokelatest to handle world-age semantics after include()
-        tool = invokelatest(getTool)
-        if !(tool isa agentTool)
-            throw(ArgumentError(
-                "getTool() in $(filepath) did not return an agentTool instance, got: $(typeof(tool))"
-            ))
-        end
-
-        push!(_registry, tool)
-        push!(tools, tool)
-        println("[toolRegistry] Loaded tool: $(tool.name) — $(tool.label)")
-    end
-
-    return tools
-end
-
-"""
-Register a single agentTool into the global registry.
-
-# Arguments
- `tool::agentTool`: The tool to register
-
-# Returns
- `Vector{agentTool}`: Updated registry
-"""
-function registerTool(tool::agentTool)::Vector{agentTool}
-    push!(_registry, tool)
-    println("[toolRegistry] Registered tool: $(tool.name)")
-    return _registry
-end
-
-"""
-Get all registered tools.
-
-# Returns
- `Vector{agentTool}`: Copy of the registry
-"""
-function getTools()::Vector{agentTool}
-    return deepcopy(_registry)
-end
-
-"""
-Clear all registered tools from the global registry.
-"""
-function clearTools()::Nothing
-    empty!(_registry)
-    println("[toolRegistry] Registry cleared")
-    return nothing
-end
-
-end # module
@@ -1,3 +1,6 @@
+using .type
+using JSON
+
 """
 Tool that writes new Julia tool module files to disk.

@@ -5,15 +8,17 @@ The agent can use this tool when it encounters a task that no existing tool
 can handle. Provide the tool's name, label, description, inputSchema, and
 execute logic as Julia code. The tool is written to `src/tools/<name>.jl`.

-After calling this tool, restart the agent so `loadTools("src/tools")` picks
-up the new file. The new tool is immediately available.
+After calling this tool, add the new file to `YiemAgent.jl` with an `include()`
+statement (after `include("toolRegistry.jl")`), then restart the agent.
+The new tool must be registered in `register_all_tools()` in `toolRegistry.jl`.

 # Example

 1. Agent calls writeTool with a spec for a "searchWine" tool
 2. writeTool generates src/tools/searchWine.jl
-3. Restart agent — loadTools() picks up the new file
-4. Agent calls searchWine with args
+3. Developer adds `include("tools/searchWine.jl")` to YiemAgent.jl
+4. Developer adds `registerTool(store, searchWineTool())` to register_all_tools()
+5. Restart agent — new tool is available

 # How It Works

@@ -22,7 +27,7 @@ tool logic as `executeCode`, and writeTool wraps it in Julia boilerplate:
  - Converts `inputSchema` Dict into Julia `Dict{String,Any}(...)` string
  - Indents `executeCode` with 4 spaces
  - Wraps it inside `function executeTool(...)::agentToolResult ... end`
-  - Appends `getTool()` returning an `agentTool` struct
+  - Appends `writeToolTool()` returning an `agentTool` struct
  - Writes the combined string to `src/tools/<name>.jl`

 # Important Notes
@@ -103,7 +108,7 @@ end
 """
 Define and return the writeTool agentTool.
 """
-function getTool()::agentTool
+function writeToolTool()::agentTool
    return agentTool(
        name = "writeTool",
        label = "Create Tool",
@@ -125,7 +130,7 @@ function getTool()::agentTool
            ),
            "required" => ["name", "label", "description", "inputSchema", "executeCode"]
        ),
-        execute = (toolCallId::String, args::Dict{String,Any}, signal::Union{Nothing,abortSignal}, onPartialResult::Function) -> begin
+        execute = (toolCallId::String, args::Dict{String,Any}, signal::Union{Nothing,abortSignal}, onPartialResult) -> begin
            tool_name = get(args, "name", "")::String
            tool_label = get(args, "label", tool_name)::String
            tool_description = get(args, "description", "")::String
@@ -248,13 +253,13 @@ function getTool()::agentTool

            tool_code = join(parts)

-            # Write the file — tool is loaded on next agent restart via loadTools()
+            # Write the file — tool must be included in YiemAgent.jl and registered in register_all_tools()
            write(filepath, tool_code)

            onPartialResult(Dict("status" => "Done"))

            return agentToolResult(
-                [textContent("Tool '$(tool_name)' written to $filepath. Restart the agent so loadTools() picks it up, then call listTools to verify.")],
+                [textContent("Tool '$(tool_name)' written to $filepath. Add include(\"tools/$(tool_name).jl\") to YiemAgent.jl and registerTool(store, $(tool_name)Tool()) to register_all_tools(), then restart the agent.")],
                Dict{Any,Any}(
                    "file" => filepath,
                    "name" => tool_name,
@@ -6,15 +6,15 @@
           modelCost, llmModel, llmUsage,
           # Message content types
           textContent, imageContent,
-           # Message types
-           userMessage, assistantMessage, toolResultMessage,
+            # Message types
+            userMessage, assistantMessageToolCall, assistantMessage, toolResultMessage,
            # Tool types
             agentTool, validateRequiredArgs,
           # Context types
           agentContext, agentState, agentToolCall, prepareNextTurnContext,
           # Loop & execution types
-           agentLoopConfig, abortSignal, agentToolResult,
-           assistantMsgCtx, afterCtx,
+           agentLoopConfig, abortSignal, agentToolResult,beforeToolCallContext, 
+           beforeToolCallResult, afterToolCallContext,
           # Event types
           toolExecStartEvent, toolExecUpdateEvent, toolExecEndEvent,
           # Agent
@@ -23,7 +23,7 @@
           preparedToolCall, immediateOutcome, executedOutcome, finalizedOutcome,
           agentToolCallBatch,
           # Functions (defined elsewhere)
-           run_agent, take_response, follow_up, stop_agent
+           runAgent, takeResponse, followUp, stopAgent


 using Dates, UUIDs, DataStructures, JSON, NATS, Base.Threads
@@ -108,6 +108,52 @@ function userMessage(; role="user", content=Vector{messageContent}(), timestamp=
    return userMessage(role, content, timestamp)
 end

+struct assistantMessageToolCall <: agentMessage   # Assistant message containing tool calls
+    role::String                            # Always "assistant"
+    toolCalls::Vector{agentToolCall}        # Tool calls to execute
+    content::Vector{messageContent}         # Reasoning/thinking content blocks
+    api::String                             # API name used (e.g., "openai")
+    provider::String                        # Provider name (e.g., "anthropic")
+    model::String                           # Model identifier
+    usage::llmUsage                         # Token usage for this message
+    stopReason::String                      # Why generation stopped (e.g., "tool_calls")
+    errorMessage::Union{String, Nothing}    # Error if generation failed
+    timestamp::Timestamp                    # When the message was received
+end
+
+"""
+Create a new assistant message containing tool calls.
+
+# Arguments
+- `role::String`: Always "assistant"
+- `toolCalls::Vector{agentToolCall}`: Tool calls to execute
+- `content::Vector{messageContent}`: Reasoning/thinking content blocks
+- `api::String`: API name used
+- `provider::String`: Provider name
+- `model::String`: Model identifier
+- `usage::llmUsage`: Token usage
+- `stopReason::String`: Why generation stopped
+- `errorMessage::Union{String, Nothing}`: Error if generation failed
+- `timestamp::Timestamp`: When the message was received
+
+# Returns
+- A new `assistantMessageToolCall` instance
+
+# Examples
+```julia
+julia> tc = agentToolCall("function", "call_1", "getWeather", Dict("city" => "Tokyo"))
+julia> msg = assistantMessageToolCall(toolCalls=[tc], stopReason="tool_calls")
+assistantMessageToolCall("assistant", [agentToolCall(...)], messageContent[], "", "", "", llmUsage(0, 0), "tool_calls", nothing, DateTime(...))
+```
+"""
+function assistantMessageToolCall(; role="assistant", toolCalls=agentToolCall[],
+    content=Vector{messageContent}(), api="", provider="", model=nothing, usage=llmUsage(0, 0),
+    stopReason="tool_calls", errorMessage=nothing, timestamp=now())
+    model_str = model isa AbstractString ? String(model) : ""
+    return assistantMessageToolCall(role, toolCalls, content, api, provider, model_str,
+                                     usage, stopReason, errorMessage, timestamp)
+end
+
 struct assistantMessage <: agentMessage     # Message from the AI assistant
    role::String                            # Always "assistant"
    content::Vector{messageContent}         # Text and/or image content
@@ -144,9 +190,10 @@ assistantMessage("assistant", [textContent("Hello!")], "", "", "gpt-4", ..., "en
 ```
 """
 function assistantMessage(; role="assistant", content=Vector{messageContent}(),
-    api="", provider="", model="", usage=llmUsage(0, 0), stopReason="end_turn",
+    api="", provider="", model=nothing, usage=llmUsage(0, 0), stopReason="end_turn",
    errorMessage=nothing, timestamp=now())
-    return assistantMessage(role, content, api, provider, model, usage, stopReason, errorMessage, timestamp)
+    model_str = model isa AbstractString ? String(model) : ""
+    return assistantMessage(role, content, api, provider, model_str, usage, stopReason, errorMessage, timestamp)
 end

 struct toolResultMessage <: agentMessage    # Result returned from a tool execution
@@ -263,7 +310,7 @@ struct agentTool                              # A tool available to the agent
    label::String                             # Human-readable tool name
    description::String                       # What the tool does
    inputSchema::Any                          # Tool parameters schema (JSON schema, MCP inputSchema format)
-    execute::Function                         # Tool execution function
+    execute                         # Tool execution function
    prepareArguments::Union{Function, Nothing}  # Optional argument preparation callback
    validateRequiredArgs::Union{Function, Nothing}  # Optional validation hook for required args
    parallelToolExecute::Bool  # Override: run tool calls sequentially or in parallel
@@ -273,7 +320,7 @@ end
 Keyword constructor for agentTool — allows `agentTool(name=..., label=..., ...)`.
 """
 function agentTool(; name::String, label::String, description::String, inputSchema::Any,
-                     execute::Function, prepareArguments::Union{Function, Nothing}=nothing,
+                     execute, prepareArguments::Union{Function, Nothing}=nothing,
                     validateRequiredArgs::Union{Function, Nothing}=nothing,
                     parallelToolExecute::Bool=false)
    return agentTool(name, label, description, inputSchema, execute,
@@ -291,7 +338,7 @@ Snapshot of the agent's conversation context.
 # Arguments
 - `systemPrompt::String`: System prompt for the agent
 - `messages::Vector{agentMessage}`: Conversation messages
- `tools::Union{Vector{agentTool}, Nothing}`: Available tools
+- `tools::Union{OrderedDict{String, agentTool}, Nothing}`: Available tools keyed by name for O(1) lookup

 # Returns
 - A new `agentContext` instance
@@ -299,7 +346,7 @@ Snapshot of the agent's conversation context.
 struct agentContext                           # Snapshot of the agent's conversation context
    systemPrompt::String                      # System prompt for the agent
    messages::Vector{agentMessage}            # Conversation messages
-    tools::Union{Vector{agentTool}, Nothing}  # Available tools
+    tools::Union{OrderedDict{String, agentTool}, Nothing}  # Available tools keyed by name
 end


@@ -308,15 +355,14 @@ end
 # ------------------------------------------------------------------------------------------------ #

 mutable struct agentState                     # Mutable runtime state of an agent
-    systemPrompt::String                      # System prompt text
-    model::llmModel                           # LLM model to use
-    tools::Vector{agentTool}                  # Available tools
+    systemPrompt::String                      # System prompt for the agent
+    model::Union{llmModel, Nothing}                           # LLM model to use
+    tools::OrderedDict{String, agentTool}     # Available tools keyed by name, insertion-ordered

    # messages history includes userMessage, assistantMessage, toolResultMessage. NO system prompt
    messages::Vector{agentMessage}            
    
    pendingToolCalls::Vector{String}          # Tool call IDs waiting for results
-    activeRun::Bool                             # is agent processing user message?
    errorMessage::Union{String, Nothing}      # Last error message
 end

@@ -329,7 +375,7 @@ new state from external references.
 # Arguments
 - `systemPrompt::String`: System prompt text
 - `model::llmModel`: LLM model to use (defaults to an unknown model)
- `tools::Vector{agentTool}`: Available tools (deep copied)
+- `tools::OrderedDict{String, agentTool}`: Available tools keyed by name (deep copied)
 - `messages::Vector{agentMessage}`: Conversation messages (deep copied)

 # Returns
@@ -338,24 +384,23 @@ new state from external references.
 # Examples
 ```julia
 julia> state = agentState(systemPrompt="You are a helpful assistant")
-agentState("You are a helpful assistant", ..., agentTool[], agentMessage[], String[], nothing)
-```
+agentState("You are a helpful assistant", OrderedDict{String, agentTool}(), agentMessage[], String[], nothing)
 """
 function agentState(
-    systemPrompt::String="",
-    model::llmModel=llmModel{String}("", "", "unknown", "unknown", "", false, String[], modelCost(0.0, 0.0, 0.0, 0.0), 0, 0),
-    tools::Vector{agentTool}=agentTool[],
-    messages::Vector{agentMessage}=agentMessage[],
+  systemPrompt::String="",
+  model=llmModel("model_1", "unknown", "unknown", "", false, String[], 
+                  modelCost(0.0, 0.0, 0.0, 0.0), 0, 0),
+  tools::OrderedDict{String, agentTool}=OrderedDict{String, agentTool}(),
+  messages::Vector{agentMessage}=agentMessage[],
 )
-    agentState(
-      systemPrompt,
-      model,
-      deepcopy(tools),
-      deepcopy(messages),
-      Vector{String}(),
-      false,
-      nothing,
-    )
+  agentState(
+    systemPrompt,
+    model,
+    deepcopy(tools),
+    deepcopy(messages),
+    Vector{String}(),
+    nothing,
+  )
 end


@@ -395,13 +440,11 @@ end
 Configuration for the agent tool execution loop.

 # Arguments
- `tools::Vector{agentTool}`: Available tools
 - `beforeToolCall::Union{Function, Nothing}`: Callback before tool execution
 - `afterToolCall::Union{Function, Nothing}`: Callback after tool execution
 - `toolExecution::String`: Execution mode — "sequential" or "parallel"
 """
 struct agentLoopConfig
-    tools::Vector{agentTool}
    beforeToolCall::Union{Function, Nothing}
    afterToolCall::Union{Function, Nothing}
    toolExecution::String
@@ -437,31 +480,36 @@ end
 Context passed to the `beforeToolCall` hook.

 # Arguments
- `message::assistantMessage`: The assistant message containing the tool call
+- `message::assistantMessageToolCall`: The assistant message containing the tool call
 - `toolCall::agentToolCall`: The tool call being prepared
 - `args::Dict{String,Any}`: Validated tool arguments
 - `context::agentContext`: Current conversation context
 """
-struct assistantMsgCtx
-    message::assistantMessage
+struct beforeToolCallContext
+    message::assistantMessageToolCall
    toolCall::agentToolCall
    args::Dict{String,Any}
    context::agentContext
 end

+struct beforeToolCallResult
+  block::Bool
+  reason::String
+end
+
 """
 Context passed to the `afterToolCall` hook.

 # Arguments
- `message::assistantMessage`: The assistant message containing the tool call
+- `message::assistantMessageToolCall`: The assistant message containing the tool call
 - `toolCall::agentToolCall`: The tool call that was executed
 - `args::Dict{String,Any}`: Tool arguments
 - `result::agentToolResult`: The raw tool result
 - `isError::Bool`: Whether execution resulted in an error
 - `context::agentContext`: Current conversation context
 """
-struct afterCtx
-    message::assistantMessage
+struct afterToolCallContext
+    message::assistantMessageToolCall
    toolCall::agentToolCall
    args::Dict{String,Any}
    result::agentToolResult
@@ -521,138 +569,6 @@ end

 abstract type agent end 

-"""
-docstring
-"""
-mutable struct yiemAgent <: agent             # High-level agent wrapper
-  _state::agentState                          # Current state (prompt, model, messages, tools, etc.)
-  
-  # user sends prompt message to agent. if agent is idle, it process user message right away. 
-  # if agent is running, it process user message after  the current tool call finished.
-  inputChannel::Channel                        
-                                              
-  # Buffers messages the user sends while the agent is busy. Processed after all inputChannel 
-  # messages are handled and the agent is idle (not using a tool call).
-  followUpChannel::Channel                    
-
-  # agent sends response message to user after processing all user messages in inputChannel 
-  # and all followUp messages.
-  outputChannel::Channel                     
-                                              
-  _agent_loop::Union{Task, Nothing}                 # agent loop running in the background
-
-  # Preprocess/transform messages and context (modify, filter, prune, inject context from memory,  
-  # reorder, ...) for a single LLM call in _process_message()'s loop.
-  # returns new Vector{agentMessage}
-  prepareContext ::Union{Function, Nothing}   
-
-  # Convert prepareContext()'s new Vector{agentMessage} to LLM message format
-  formatMsgForLLM::Function    
-
-  # Actually invoke the LLM to get a completion response. The LLM response comes back as an 
-  # assistantMessage whose content is an array of content blocks. 
-  # Each block has a type — "text", "thinking", or "toolCall". 
-  # The code filters for type === "toolCall" blocks, then passes them to executeToolCalls().
-  llmCall::Function                           
-                                              
-  # Callback invoked before executing a tool call (ask for user permission/confirmation/abort, etc..)
-  beforeToolCall::Union{Function, Nothing}    
-
-  executeToolCalls::Function                  # execute tool calls ()
-  
-  # Callback invoked after executing a tool call to sanitize tools output so the output is ready 
-  # to be converted into toolResults message
-  afterToolCall::Union{Function, Nothing}     
-  # prepareNextTurn::Union{Function, Nothing}   # Callback to prepare the next conversation turn
-  # prepareNextTurnWithContext::Union{Function, Nothing}  # Same but receives context
-  sessionId::Union{String, Nothing}           # Optional session identifier
-  maxRetryDelayMs::Union{Int64, Nothing}      # Maximum delay between retries (ms)
-  parallelToolExecute::Bool                   # Default: false
-  agentEventSink::Function                    # agent emits its status via this function
-end
-
-"""
-Create a new yiemAgent instance with a background loop task.
-
-Spawns a background `@spawn` task that runs the agent loop, listening
-on `inputChannel` and `followUpChannel` channels concurrently.
-
-# Keyword Arguments
- `systemPrompt::String`: System prompt for the agent
- `model`: LLM model to use
- `tools::Vector{agentTool}`: Available tools (default: empty)
- `messages::Vector{agentMessage}`: Initial conversation messages (default: empty)
- `formatMsgForLLM::Function`: Convert agent messages to LLM message format (default: `defaultformatMsgForLLM`)
- `llmCall::Function`: Function to invoke the LLM (required)
- `prepareContext::Union{Function, Nothing}`: Preprocess/transform messages before sending to LLM (default: `nothing`)
- `beforeToolCall::Union{Function, Nothing}`: Callback invoked before executing a tool call (default: `nothing`)
- `afterToolCall::Union{Function, Nothing}`: Callback invoked after executing a tool call (default: `nothing`)
- `prepareNextTurn::Union{Function, Nothing}`: Callback to prepare the next conversation turn (default: `nothing`)
- `prepareNextTurnWithContext::Union{Function, Nothing}`: Same but receives context (default: `nothing`)
- `sessionId::Union{String, Nothing}`: Optional session identifier (default: `nothing`)
- `maxRetryDelayMs::Union{Int64, Nothing}`: Maximum delay between retries in milliseconds (default: `nothing`)
- `parallelToolExecute::Bool`: Run tool calls in parallel (default: `false`)
- `agentEventSink::Function`: Callback to receive agent events
-
-# Returns
- A new `yiemAgent` instance with an active background task
-
-# Examples
-```julia
-julia> agent = yiemAgent(systemPrompt="You are a helpful assistant", model=my_model)
-yiemAgent(agentState(...), Channel(...), Channel(...), Channel(...), ..., ...)
-```
-"""
-function yiemAgent(
-  ; systemPrompt::String="You are helpful assistant.",
-    model=nothing,
-    tools::Vector{agentTool}=agentTool[],
-    messages::Vector{agentMessage}=agentMessage[],
-    prepareContext::Union{Function, Nothing}=nothing,
-    formatMsgForLLM::Function=defaultformatMsgForLLM,
-    llmCall::Function,
-    beforeToolCall::Union{Function, Nothing}=nothing,
-    afterToolCall::Union{Function, Nothing}=nothing,
-    # prepareNextTurn::Union{Function, Nothing}=nothing,
-    # prepareNextTurnWithContext::Union{Function, Nothing}=nothing,
-    sessionId::Union{String, Nothing}=nothing,
-    maxRetryDelayMs::Union{Int64, Nothing}=nothing,
-    parallelToolExecute::Bool=false,
-    agentEventSink::Function,
-  )
-  # Create channels: input (user -> agent), followUp (async queue), output (agent -> user)
-  inputChannel    = Channel(16)
-  followUp    = Channel(32)
-  outputChannel   = Channel(16)
-
-  # Create struct with a placeholder task, then spawn and replace it
-  agent = yiemAgent(
-    agentState(systemPrompt, model, tools, messages),
-    inputChannel,
-    followUp,
-    outputChannel,
-    nothing,  # placeholder — replaced below
-    prepareContext,
-    formatMsgForLLM,
-    llmCall,
-    beforeToolCall,
-    afterToolCall,
-    # prepareNextTurn,
-    # prepareNextTurnWithContext,
-    sessionId,
-    maxRetryDelayMs,
-    parallelToolExecute,
-    agentEventSink,
-  )
-
-  # Spawn the background loop and attach it
-  agent._agent_loop = @spawn _agent_loop(agent)
-
-  return agent
-end
-
-
-
 """
    preparedToolCall(tool, toolCall, args)

@@ -1,9 +1,11 @@
 module utils

-export clearhistory, availableWineToText, prepareContext, formatMsgForLLM, validateRequiredArgs, validateToolArguments, _userMessageToOpenAI, 
-        _assistantMessageToOpenAI, _toolResultMessageToOpenAI, _messageContentToBlocks
+export clearhistory, availableWineToText, prepareContext, formatMsgForLLM, validateRequiredArgs, 
+      validateToolArguments, _userMessageToOpenAI, 
+      _assistantMessageToOpenAI, _toolResultMessageToOpenAI, _messageContentToBlocks, _toolsToOpenAI,
+      beforeToolCall, afterToolCall, agentEventSink

-using UUIDs, Dates, DataStructures, HTTP, JSON
+using UUIDs, Dates, DataStructures, HTTP, JSON, NATS
 using GeneralUtils
 using ..type

@@ -73,7 +75,6 @@ function availableWineToText(vecd::Vector)::String
 end


-
 """
    prepareContext(state::agentState) -> agentContext

@@ -108,7 +109,7 @@ prepareContext(state).messages == deepcopy(state.messages)
 # end
 ```
 """
-function prepareContext(state::agentState)::agentContext
+function prepareContext(state::agentState, agentEventSink)::agentContext
  
  #TODO filter tools from state.tools based on user intend in user message and tool description
  filteredTools = state.tools
@@ -155,7 +156,7 @@ formatMsgForLLm(ctx) == Dict("messages" => [
 ])
 ```
 """
-function formatMsgForLLM(ctx::agentContext)::Dict{String, Any}
+function formatMsgForLLM(ctx::agentContext, agentEventSink)::Dict{String, Any}

  """ openai message format example
  msg = Dict(
@@ -183,19 +184,31 @@ function formatMsgForLLM(ctx::agentContext)::Dict{String, Any}
          Dict("type" => "text", "text" => "let me check."),
        ]
      ),
+    ],
+    "tools"=> [
      Dict(
-        "role" => "toolResult",
-        "content" => [
-          Dict("type" => "text", "text" => "name: Chateau Montelena ..."),
-        ]
-      ),
+        "type" => "function",
+        "function" => Dict(
+          "name" => "getWeather",
+          "description" => "Get current weather",
+          "parameters" => Dict(
+            "type" => "object",
+            "properties" => Dict(
+              "city" => Dict("type" => "string")
+            ),
+            "required" => ["city"]
+          )
+        )
+      )
    ],
    "temperature" => 0.7
  )
  """

+  openaiReadyMsg = Dict{String, Any}()
+  # openaiReadyMsg["model"] = "gemma-4-E4B-it-UD-Q4_K_XL"
  messages = Vector{Dict{String, Any}}()
-
+  agentEventSink("formatMsgForLLM 1")
  # System prompt as system message
  if !isempty(ctx.systemPrompt)
    push!(messages, Dict(
@@ -203,19 +216,113 @@ function formatMsgForLLM(ctx::agentContext)::Dict{String, Any}
      "content" => [Dict("type" => "text", "text" => ctx.systemPrompt)]
    ))
  end
-
+  agentEventSink("formatMsgForLLM 2")
  # Conversation messages
  for msg in ctx.messages
    if msg isa userMessage
      push!(messages, _userMessageToOpenAI(msg))
+    elseif msg isa assistantMessageToolCall
+      push!(messages, _assistantMessageToolCallToOpenAI(msg))
    elseif msg isa assistantMessage
      push!(messages, _assistantMessageToOpenAI(msg))
    elseif msg isa toolResultMessage
      push!(messages, _toolResultMessageToOpenAI(msg))
    end
  end
+  agentEventSink("formatMsgForLLM 3")
+  # Convert ctx.tools into OpenAI tools format
+  tools_array = _toolsToOpenAI(ctx.tools, agentEventSink)
+  agentEventSink("formatMsgForLLM 4")
+  openaiReadyMsg["messages"] = messages
+  openaiReadyMsg["temperature"] = 0.7
+
+  if !isempty(tools_array)
+    openaiReadyMsg["tools"] = tools_array
+  end
+
+  return openaiReadyMsg
+end
+
+"""
+    beforeToolCall(context::beforeToolCallContext, signal::abortSignal) -> beforeToolCallResult
+
+Callback invoked before executing a tool call. Use this hook to inspect
+the tool call and decide whether to allow, block, or modify it.
+
+Common use cases:
+  - Request user approval via UI before running destructive tools.
+  - Validate business rules that cannot be expressed in the JSON schema.
+  - Check final context (e.g. session state, rate limits, permissions).
+
+# Arguments
+- `context::beforeToolCallContext`: Contains the assistant message, tool call,
+  validated arguments, and current conversation context.
+- `signal::abortSignal`: Signal that may be set to abort the operation.
+
+# Returns
+- `beforeToolCallResult(false, "N/A")` to allow the call to proceed.
+- `beforeToolCallResult(true, "Reason")` to block the call with a reason.
+- `nothing` is treated as allow (equivalent to `beforeToolCallResult(false, "N/A")`).
+
+# Example
+```julia
+function beforeToolCall(context::beforeToolCallContext, signal::abortSignal)
+    if context.toolCall.name == "deleteFile"
+        # Block file deletion unless explicitly approved
+        return beforeToolCallResult(true, "User must approve file deletion")
+    end
+    return beforeToolCallResult(false, "N/A")
+end
+```
+"""
+function beforeToolCall(context::beforeToolCallContext, signal::abortSignal
+  )::beforeToolCallResult
+  
+  # final context check
+
+  # seek user approval via UI
+
+  # other check
+  
+  return beforeToolCallResult(false, "N/A")
+end
+
+"""
+    afterToolCall(context::afterToolCallContext, signal::abortSignal) -> Union{agentToolResult, Nothing}
+
+Callback invoked after a tool call finishes executing (before and after errors).
+Use this hook to post-process the tool result before it is fed back to the LLM.
+
+Common use cases:
+  - Mask sensitive data (API keys, tokens) from result content.
+  - Normalize usage tracking data into a consistent format.
+  - Inspect the result and set `terminate: true` based on business logic
+    (e.g. "if deployment failed, stop the agent rather than retrying").
+  - Wrap error results in friendlier messages for the LLM to understand.
+
+# Arguments
+- `context::afterToolCallContext`: Contains the assistant message, tool call,
+  arguments, raw result, error status, and current conversation context.
+- `signal::abortSignal`: Signal that may be set to abort the operation.
+
+# Returns
+- `nothing` to pass the result through unchanged.
+- `agentToolResult(...)` to return a modified result (content, details, usage,
+  terminate flag can all be overridden).
+
+"""
+function afterToolCall(context::afterToolCallContext, signal::abortSignal
+  )::Union{agentToolResult, Nothing}
+
+  # modify context.result if needed and return agentToolResult
+  
+  return nothing
+end
+
+
+#TODO
+function agentEventSink(x)
  
-  return Dict("messages" => messages)
 end


@@ -230,6 +337,44 @@ function _userMessageToOpenAI(msg::userMessage)::Dict{String, Any}
 end


+"""
+Convert an assistantMessageToolCall to OpenAI message format.
+
+Produces a message with role="assistant", content=null, and a tool_calls array:
+{
+  "role": "assistant",
+  "content": null,
+  "tool_calls": [
+    {
+      "id": "call_1",
+      "type": "function",
+      "function": {
+        "name": "get_weather",
+        "arguments": "{\"location\": \"San Francisco, CA\"}"
+      }
+    }
+  ]
+}
+"""
+function _assistantMessageToolCallToOpenAI(msg::assistantMessageToolCall)::Dict{String, Any}
+  tool_calls = Dict{String, Any}[]
+  for tc in msg.toolCalls
+    push!(tool_calls, Dict(
+      "id" => tc.id,
+      "type" => tc.type,
+      "function" => Dict(
+        "name" => tc.name,
+        "arguments" => JSON.json(tc.arguments)
+      )
+    ))
+  end
+  return Dict(
+    "role" => "assistant",
+    "content" => nothing,
+    "tool_calls" => tool_calls
+  )
+end
+
 """
 Convert an assistantMessage to OpenAI message format.
 """
@@ -279,6 +424,40 @@ function _messageContentToBlocks(contents::Vector{messageContent})::Vector{Dict{
 end


+"""
+    _toolsToOpenAI(tools::Union{OrderedDict{String, agentTool}, Nothing}) -> Vector{Dict{String, Any}}
+
+Convert an OrderedDict of agentTool definitions into OpenAI function tool format.
+
+Returns an empty vector when `tools` is `nothing` or empty.
+
+# Examples
+```julia
+_toolsToOpenAI(nothing)  # => Dict{String, Any}[]
+_toolsToOpenAI(tools)    # => [Dict("type" => "function", "function" => Dict("name" => "getWeather", ...))]
+```
+"""
+function _toolsToOpenAI(tools::Union{OrderedDict{String, agentTool}, Nothing}, agentEventSink)::Vector{Dict{String, Any}}
+  tools_array = Vector{Dict{String, Any}}()
+  agentEventSink("_toolsToOpenAI 1")
+  agentEventSink(string(typeof(tools)))
+  if tools !== nothing
+    for (_, tool) in tools
+      push!(tools_array, Dict(
+        "type" => "function",
+        "function" => Dict(
+          "name" => tool.name,
+          "description" => tool.description,
+          "parameters" => tool.inputSchema
+        )
+      ))
+    end
+  end
+  agentEventSink("_toolsToOpenAI 2")
+  return tools_array
+end
+
+
 """
    validateRequiredArgs(args::Dict{String,Any}, inputSchema::Dict{String,Any}) -> Union{Nothing,String}

@@ -0,0 +1,638 @@
+using Test
+using YiemAgent
+using YiemAgent.agentCore
+using YiemAgent.type
+using JSON
+
+# Import the function from the private module scope
+import YiemAgent.agentCore: _extractToolCalls
+
+@testset "_extractToolCalls" begin
+
+    # ------------------------------------------------------------------ #
+    # Format 1: response["message"]["tool_calls"] (LMStudio.jl style)     #
+    # ------------------------------------------------------------------ #
+
+    @testset "single tool call via message format" begin
+        response = Dict{String,Any}(
+            "finish_reason" => "tool_calls",
+            "index" => 0,
+            "message" => Dict{String,Any}(
+                "role" => "assistant",
+                "content" => "",
+                "reasoning_content" => "Let me check the weather.",
+                "tool_calls" => Any[
+                    Dict{String,Any}(
+                        "type" => "function",
+                        "function" => Dict{String,Any}(
+                            "name" => "getWeather",
+                            "arguments" => "{\"city\":\"Bangkok, Thailand\"}",
+                        ),
+                        "id" => "tc_001",
+                    )
+                ],
+            ),
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == true
+        @test length(tc_list) == 1
+        @test tc_list[1].name == "getWeather"
+        @test tc_list[1].id == "tc_001"
+        @test tc_list[1].type == "function"
+        @test tc_list[1].arguments["city"] == "Bangkok, Thailand"
+        @test assistant_msg isa assistantMessage
+        @test assistant_msg.role == "assistant"
+        @test assistant_msg.stopReason == "tool_calls"
+        @test length(assistant_msg.content) == 1
+        @test assistant_msg.content[1] isa textContent
+        @test assistant_msg.content[1].text == "Let me check the weather."
+    end
+
+    @testset "multiple tool calls via message format" begin
+        response = Dict{String,Any}(
+            "message" => Dict{String,Any}(
+                "role" => "assistant",
+                "content" => "",
+                "tool_calls" => Any[
+                    Dict{String,Any}(
+                        "type" => "function",
+                        "function" => Dict{String,Any}(
+                            "name" => "getWeather",
+                            "arguments" => "{\"city\":\"Tokyo, Japan\"}",
+                        ),
+                        "id" => "tc_001",
+                    ),
+                    Dict{String,Any}(
+                        "type" => "function",
+                        "function" => Dict{String,Any}(
+                            "name" => "getTime",
+                            "arguments" => "{\"timezone\":\"Asia/Tokyo\"}",
+                        ),
+                        "id" => "tc_002",
+                    ),
+                ],
+            ),
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == true
+        @test length(tc_list) == 2
+        @test tc_list[1].name == "getWeather"
+        @test tc_list[1].arguments["city"] == "Tokyo, Japan"
+        @test tc_list[2].name == "getTime"
+        @test tc_list[2].arguments["timezone"] == "Asia/Tokyo"
+        @test assistant_msg.role == "assistant"
+    end
+
+    @testset "tool call with empty arguments string" begin
+        response = Dict{String,Any}(
+            "message" => Dict{String,Any}(
+                "role" => "assistant",
+                "tool_calls" => Any[
+                    Dict{String,Any}(
+                        "type" => "function",
+                        "function" => Dict{String,Any}(
+                            "name" => "listTools",
+                            "arguments" => "{}",
+                        ),
+                        "id" => "tc_empty",
+                    ),
+                ],
+            ),
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == true
+        @test length(tc_list) == 1
+        @test tc_list[1].name == "listTools"
+        @test tc_list[1].arguments == Dict{String,Any}()
+        @test assistant_msg.stopReason == "end_turn"
+    end
+
+    @testset "tool call with missing id falls back to uuid" begin
+        response = Dict{String,Any}(
+            "message" => Dict{String,Any}(
+                "role" => "assistant",
+                "tool_calls" => Any[
+                    Dict{String,Any}(
+                        "type" => "function",
+                        "function" => Dict{String,Any}(
+                            "name" => "getTime",
+                            "arguments" => "{\"city\":\"NYC\"}",
+                        ),
+                    ),
+                ],
+            ),
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == true
+        @test length(tc_list) == 1
+        @test !isempty(tc_list[1].id)
+        @test tc_list[1].name == "getTime"
+    end
+
+    @testset "tool call with non-string arguments (pre-parsed dict)" begin
+        response = Dict{String,Any}(
+            "message" => Dict{String,Any}(
+                "role" => "assistant",
+                "tool_calls" => Any[
+                    Dict{String,Any}(
+                        "type" => "function",
+                        "function" => Dict{String,Any}(
+                            "name" => "getWeather",
+                            "arguments" => Dict{String,Any}("city" => "London", "units" => "fahrenheit"),
+                        ),
+                        "id" => "tc_parsed",
+                    ),
+                ],
+            ),
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == true
+        @test length(tc_list) == 1
+        @test tc_list[1].arguments["city"] == "London"
+        @test tc_list[1].arguments["units"] == "fahrenheit"
+    end
+
+    @testset "tool call with api/provider/model/usage metadata" begin
+        response = Dict{String,Any}(
+            "api" => "openai",
+            "provider" => "anthropic",
+            "model" => "claude-3-opus",
+            "message" => Dict{String,Any}(
+                "role" => "assistant",
+                "tool_calls" => Any[
+                    Dict{String,Any}(
+                        "type" => "function",
+                        "function" => Dict{String,Any}(
+                            "name" => "getTime",
+                            "arguments" => "{}",
+                        ),
+                        "id" => "tc_meta",
+                    ),
+                ],
+            ),
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == true
+        @test assistant_msg.api == "openai"
+        @test assistant_msg.provider == "anthropic"
+        @test assistant_msg.model == "claude-3-opus"
+    end
+
+    # --------------------------------------------------------------- #
+    # Format 2: response.content blocks (OpenAI API style)            #
+    # --------------------------------------------------------------- #
+
+    @testset "content blocks with tool_calls" begin
+        response = Dict{String,Any}(
+            "content" => Any[
+                Dict{String,Any}("type" => "text", "text" => "Let me check."),
+                Dict{String,Any}(
+                    "type" => "tool_calls",
+                    "tool_calls" => Any[
+                        Dict{String,Any}(
+                            "type" => "function",
+                            "function" => Dict{String,Any}(
+                                "name" => "getWeather",
+                                "arguments" => "{\"city\":\"Paris\"}",
+                            ),
+                            "id" => "tc_block_1",
+                        ),
+                    ],
+                ),
+            ],
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == true
+        @test length(tc_list) == 1
+        @test tc_list[1].name == "getWeather"
+        @test tc_list[1].arguments["city"] == "Paris"
+        # text block before tool_calls should be included in content
+        @test length(assistant_msg.content) == 1
+        @test assistant_msg.content[1].text == "Let me check."
+    end
+
+    @testset "content blocks with tool_call (single-call format)" begin
+        response = Dict{String,Any}(
+            "content" => Any[
+                Dict{String,Any}(
+                    "type" => "tool_call",
+                    "id" => "tc_single",
+                    "name" => "getTime",
+                    "arguments" => Dict{String,Any}("timezone" => "Europe/London"),
+                ),
+            ],
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == true
+        @test length(tc_list) == 1
+        @test tc_list[1].name == "getTime"
+        @test tc_list[1].id == "tc_single"
+        @test tc_list[1].arguments["timezone"] == "Europe/London"
+    end
+
+    @testset "content blocks with reasoning and text" begin
+        response = Dict{String,Any}(
+            "content" => Any[
+                Dict{String,Any}("type" => "reasoning", "text" => "Thinking..."),
+                Dict{String,Any}("type" => "text", "text" => "Here's the answer."),
+            ],
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == false
+        @test length(tc_list) == 0
+        @test length(assistant_msg.content) == 2
+        @test assistant_msg.content[1].text == "Thinking..."
+        @test assistant_msg.content[2].text == "Here's the answer."
+    end
+
+    @testset "content blocks with text and tool_call (tool_call not in content)" begin
+        response = Dict{String,Any}(
+            "content" => Any[
+                Dict{String,Any}("type" => "text", "text" => "Sure, I'll check."),
+                Dict{String,Any}(
+                    "type" => "tool_call",
+                    "id" => "tc_mix",
+                    "name" => "getWeather",
+                    "arguments" => Dict{String,Any}("city" => "London"),
+                ),
+            ],
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == true
+        @test length(tc_list) == 1
+        @test tc_list[1].name == "getWeather"
+        # text block included, tool_call block excluded from content
+        @test length(assistant_msg.content) == 1
+        @test assistant_msg.content[1].text == "Sure, I'll check."
+    end
+
+    # ------------------------------------------------------------------ #
+    # assistantMessage construction                                       #
+    # ------------------------------------------------------------------ #
+
+    @testset "assistantMessage with error_message and errorMessage fallback" begin
+        response = Dict{String,Any}(
+            "error_message" => "rate limit",
+            "content" => Any[Dict{String,Any}("type" => "text", "text" => "fail")],
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == false
+        @test assistant_msg.errorMessage == "rate limit"
+    end
+
+    @testset "assistantMessage with usage tracking" begin
+        response = Dict{String,Any}(
+            "content" => Any[Dict{String,Any}("type" => "text", "text" => "hi")],
+            "usage" => llmUsage(100, 50),
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test assistant_msg.usage.inputTokens == 100
+        @test assistant_msg.usage.outputTokens == 50
+    end
+
+    @testset "assistantMessage with invalid usage defaults to zero" begin
+        response = Dict{String,Any}(
+            "content" => Any[Dict{String,Any}("type" => "text", "text" => "hi")],
+            "usage" => "invalid",
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test assistant_msg.usage.inputTokens == 0
+        @test assistant_msg.usage.outputTokens == 0
+    end
+
+    @testset "reasoning_content as textContent" begin
+        response = Dict{String,Any}(
+            "reasoning_content" => textContent("internal thought"),
+            "content" => Any[Dict{String,Any}("type" => "text", "text" => "output")],
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test length(assistant_msg.content) == 2
+        @test assistant_msg.content[1].text == "internal thought"
+        @test assistant_msg.content[2].text == "output"
+    end
+
+    # ------------------------------------------------------------------ #
+    # No tool call cases                                                  #
+    # ------------------------------------------------------------------ #
+
+    @testset "no tool calls found" begin
+        response = Dict{String,Any}(
+            "content" => Any[
+                Dict{String,Any}("type" => "text", "text" => "Hello world."),
+            ],
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == false
+        @test length(tc_list) == 0
+        @test assistant_msg.stopReason == "end_turn"
+    end
+
+    @testset "empty message" begin
+        response = Dict{String,Any}()
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == false
+        @test length(tc_list) == 0
+        @test assistant_msg.role == "assistant"
+        @test assistant_msg.stopReason == "end_turn"
+        @test length(assistant_msg.content) == 0
+    end
+
+    @testset "message with empty tool_calls array" begin
+        response = Dict{String,Any}(
+            "message" => Dict{String,Any}(
+                "role" => "assistant",
+                "tool_calls" => Any[],
+            ),
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == false
+        @test length(tc_list) == 0
+        @test assistant_msg.role == "assistant"
+    end
+
+    @testset "message field is not a Dict" begin
+        response = Dict{String,Any}(
+            "message" => "not a dict",
+            "content" => Any[Dict{String,Any}("type" => "text", "text" => "fallback")],
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == false
+        @test length(tc_list) == 0
+        @test length(assistant_msg.content) == 1
+    end
+
+    @testset "Format 1 takes priority over Format 2" begin
+        response = Dict{String,Any}(
+            "message" => Dict{String,Any}(
+                "role" => "assistant",
+                "tool_calls" => Any[
+                    Dict{String,Any}(
+                        "type" => "function",
+                        "function" => Dict{String,Any}(
+                            "name" => "getWeather",
+                            "arguments" => "{\"city\":\"Format1\"}",
+                        ),
+                        "id" => "tc_fmt1",
+                    ),
+                ],
+            ),
+            "content" => Any[
+                Dict{String,Any}(
+                    "type" => "tool_call",
+                    "id" => "tc_fmt2",
+                    "name" => "getTime",
+                    "arguments" => Dict{String,Any}("city" => "Format2"),
+                ),
+            ],
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == true
+        @test length(tc_list) == 1
+        @test tc_list[1].name == "getWeather"
+    end
+
+    # ------------------------------------------------------------------ #
+    # Edge cases                                                          #
+    # ------------------------------------------------------------------ #
+
+    @testset "tool call with null arguments" begin
+        response = Dict{String,Any}(
+            "message" => Dict{String,Any}(
+                "role" => "assistant",
+                "tool_calls" => Any[
+                    Dict{String,Any}(
+                        "type" => "function",
+                        "function" => Dict{String,Any}(
+                            "name" => "getTime",
+                            "arguments" => nothing,
+                        ),
+                        "id" => "tc_null",
+                    ),
+                ],
+            ),
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == true
+        @test length(tc_list) == 1
+        @test tc_list[1].name == "getTime"
+    end
+
+    @testset "tool call with missing function key" begin
+        response = Dict{String,Any}(
+            "message" => Dict{String,Any}(
+                "role" => "assistant",
+                "tool_calls" => Any[
+                    Dict{String,Any}(
+                        "type" => "function",
+                        "id" => "tc_nofunc",
+                    ),
+                ],
+            ),
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == true
+        @test length(tc_list) == 1
+        @test tc_list[1].name == ""
+    end
+
+    @testset "tool call with missing name in function block" begin
+        response = Dict{String,Any}(
+            "message" => Dict{String,Any}(
+                "role" => "assistant",
+                "tool_calls" => Any[
+                    Dict{String,Any}(
+                        "type" => "function",
+                        "function" => Dict{String,Any}("arguments" => "{}"),
+                        "id" => "tc_noname",
+                    ),
+                ],
+            ),
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == true
+        @test length(tc_list) == 1
+        @test tc_list[1].name == ""
+    end
+
+    @testset "message format with JSON.Object (JSON.parse result)" begin
+        json_str = JSON.json(Dict(
+            "message" => Dict(
+                "role" => "assistant",
+                "tool_calls" => [
+                    Dict(
+                        "type" => "function",
+                        "function" => Dict("name" => "getWeather", "arguments" => "{\"city\":\"Test\"}"),
+                        "id" => "tc_jsonobj",
+                    ),
+                ],
+            ),
+        ))
+        parsed = JSON.parse(json_str)
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(parsed)
+        @test has_toolcalls == true
+        @test length(tc_list) == 1
+        @test tc_list[1].name == "getWeather"
+        @test tc_list[1].arguments["city"] == "Test"
+    end
+
+    @testset "tool_calls block with mixed content types (text + tool_calls)" begin
+        response = Dict{String,Any}(
+            "content" => Any[
+                Dict{String,Any}("type" => "text", "text" => "I'll check both."),
+                Dict{String,Any}(
+                    "type" => "tool_calls",
+                    "tool_calls" => Any[
+                        Dict{String,Any}(
+                            "type" => "function",
+                            "function" => Dict{String,Any}(
+                                "name" => "getWeather",
+                                "arguments" => "{\"city\":\"London\"}",
+                            ),
+                            "id" => "tc_mix1",
+                        ),
+                        Dict{String,Any}(
+                            "type" => "function",
+                            "function" => Dict{String,Any}(
+                                "name" => "getTime",
+                                "arguments" => "{\"timezone\":\"UTC\"}",
+                            ),
+                            "id" => "tc_mix2",
+                        ),
+                    ],
+                ),
+            ],
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == true
+        @test length(tc_list) == 2
+        @test tc_list[1].name == "getWeather"
+        @test tc_list[2].name == "getTime"
+        @test length(assistant_msg.content) == 1
+        @test assistant_msg.content[1].text == "I'll check both."
+    end
+
+    @testset "tool_call block without arguments field" begin
+        response = Dict{String,Any}(
+            "content" => Any[
+                Dict{String,Any}(
+                    "type" => "tool_call",
+                    "id" => "tc_noargs",
+                    "name" => "getTime",
+                ),
+            ],
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == true
+        @test length(tc_list) == 1
+        @test tc_list[1].arguments == Dict{String,Any}()
+    end
+
+    @testset "tool_calls block with empty tool_calls array" begin
+        response = Dict{String,Any}(
+            "content" => Any[
+                Dict{String,Any}(
+                    "type" => "tool_calls",
+                    "tool_calls" => Any[],
+                ),
+            ],
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == false
+        @test length(tc_list) == 0
+    end
+
+    @testset "tool_calls block with non-AbstractDict elements" begin
+        response = Dict{String,Any}(
+            "content" => Any[
+                Dict{String,Any}(
+                    "type" => "tool_calls",
+                    "tool_calls" => Any["not a dict", 42, nothing],
+                ),
+            ],
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == false
+        @test length(tc_list) == 0
+    end
+
+    @testset "content field is not a Vector" begin
+        response = Dict{String,Any}(
+            "content" => "not a vector",
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == false
+        @test length(tc_list) == 0
+        @test length(assistant_msg.content) == 0
+    end
+
+    @testset "Dict-based response with all metadata fields" begin
+        response = Dict{String,Any}(
+            "api" => "openai",
+            "provider" => "anthropic",
+            "model" => "claude-3-sonnet",
+            "content" => Any[
+                Dict{String,Any}(
+                    "type" => "tool_call",
+                    "id" => "tc_meta",
+                    "name" => "getTime",
+                    "arguments" => Dict{String,Any}("city" => "Seoul"),
+                ),
+            ],
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == true
+        @test length(tc_list) == 1
+        @test tc_list[1].name == "getTime"
+        @test tc_list[1].arguments["city"] == "Seoul"
+        @test assistant_msg.api == "openai"
+        @test assistant_msg.provider == "anthropic"
+        @test assistant_msg.model == "claude-3-sonnet"
+    end
+
+    @testset "default role is assistant" begin
+        response = Dict{String,Any}(
+            "content" => Any[Dict{String,Any}("type" => "text", "text" => "no role specified")],
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test assistant_msg.role == "assistant"
+    end
+
+    @testset "tool call with custom role in message format" begin
+        response = Dict{String,Any}(
+            "message" => Dict{String,Any}(
+                "role" => "custom_role",
+                "tool_calls" => Any[
+                    Dict{String,Any}(
+                        "type" => "function",
+                        "function" => Dict{String,Any}(
+                            "name" => "getWeather",
+                            "arguments" => "{}",
+                        ),
+                        "id" => "tc_role",
+                    ),
+                ],
+            ),
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test assistant_msg.role == "custom_role"
+    end
+
+    @testset "image content block handling" begin
+        response = Dict{String,Any}(
+            "content" => Any[
+                Dict{String,Any}(
+                    "type" => "image_url",
+                    "image_url" => Dict("url" => "data:image/png;base64,abc123"),
+                ),
+                Dict{String,Any}("type" => "text", "text" => "What is this?"),
+            ],
+        )
+        has_toolcalls, tc_list, assistant_msg = _extractToolCalls(response)
+        @test has_toolcalls == false
+        @test length(assistant_msg.content) == 2
+        @test assistant_msg.content[1] isa textContent
+        @test assistant_msg.content[1].text == ""
+        @test assistant_msg.content[2].text == "What is this?"
+    end
+
+end
@@ -1,136 +0,0 @@
-using Test
-using YiemAgent
-using YiemAgent.toolRegistry
-using YiemAgent.type
-
-# Path to the real tools directory
-TOOLS_DIR = joinpath(@__DIR__, "..", "src", "tools")
-
-@testset "loadTools" begin
-
-    # ------------------------------------------------------------------ #
-    # 1. loadTools throws on non-existent directory                      #
-    # ------------------------------------------------------------------ #
-    @test_throws ArgumentError loadTools("/nonexistent/dir/that/does/not/exist")
-
-    # ------------------------------------------------------------------ #
-    # 2. loadTools throws if a .jl file does not define getTool()        #
-    #    Must run BEFORE any other loadTools call (getTool binding       #
-    #    persists in module scope after include()).                      #
-    # ------------------------------------------------------------------ #
-    bad_dir = mktempdir()
-    write(joinpath(bad_dir, "noTool.jl"), "x = 42\n")
-    @test_throws ArgumentError loadTools(bad_dir)
-
-    # ------------------------------------------------------------------ #
-    # 3. loadTools loads actual tool files from src/tools/               #
-    # ------------------------------------------------------------------ #
-    loaded = loadTools(TOOLS_DIR)
-    @test !isempty(loaded)
-    @test length(loaded) == 3
-
-    names = [t.name for t in loaded]
-    @test "getTime" in names
-    @test "getWeather" in names
-    @test "writeTool" in names
-
-    # ------------------------------------------------------------------ #
-    # 4. loadTools returns tools sorted alphabetically by filename       #
-    #    (getTime.jl < getWeather.jl < writeTool.jl)                      #
-    #    because 'T' < 'W' in ASCII                                       #
-    # ------------------------------------------------------------------ #
-    @test loaded[1].name == "getTime"
-    @test loaded[2].name == "getWeather"
-    @test loaded[3].name == "writeTool"
-
-    # ------------------------------------------------------------------ #
-    # 5. Verify loaded tool fields are correct                           #
-    # ------------------------------------------------------------------ #
-    # getTime
-    time_tool = loaded[1]
-    @test time_tool.name == "getTime"
-    @test time_tool.label == "Time Lookup"
-    @test time_tool.validateRequiredArgs !== nothing
-    @test time_tool.parallelToolExecute == false
-    @test time_tool.inputSchema["required"] == Any[]
-
-    # getWeather
-    weather = loaded[2]
-    @test weather.name == "getWeather"
-    @test weather.label == "Weather Lookup"
-    @test weather.execute !== nothing
-    @test weather.parallelToolExecute == false
-    @test weather.inputSchema["required"] == ["city"]
-
-    # writeTool
-    wt = loaded[3]
-    @test wt.name == "writeTool"
-    @test wt.label == "Create Tool"
-    @test wt.execute !== nothing
-    @test "name" in wt.inputSchema["required"]
-    @test "executeCode" in wt.inputSchema["required"]
-
-    # ------------------------------------------------------------------ #
-    # 6. Tool execution returns valid results                            #
-    # ------------------------------------------------------------------ #
-    sig = nothing
-    op = x -> x  # no-op partial result callback
-
-    # execute getTime
-    result_t = time_tool.execute("call-1", Dict{String,Any}("city" => "Tokyo"), sig, op)
-    @test result_t isa agentToolResult
-    @test result_t.content[1] isa textContent
-    @test occursin("Tokyo", result_t.content[1].text)
-
-    # execute getTime with timezone
-    result_tz = time_tool.execute("call-2", Dict{String,Any}("timezone" => "America/New_York"), sig, op)
-    @test result_tz isa agentToolResult
-    @test occursin("America/New_York", result_tz.content[1].text)
-
-    # execute getWeather
-    result_w = weather.execute("call-3", Dict{String,Any}("city" => "Bangkok"), sig, op)
-    @test result_w isa agentToolResult
-    @test result_w.content[1] isa textContent
-    @test occursin("Bangkok", result_w.content[1].text)
-
-    # execute getWeather with units
-    result_w2 = weather.execute("call-4", Dict{String,Any}("city" => "London", "units" => "fahrenheit"), sig, op)
-    @test occursin("72°F", result_w2.content[1].text)
-
-    # ------------------------------------------------------------------ #
-    # 7. getTools / registerTool / clearTools                            #
-    # ------------------------------------------------------------------ #
-    registry_tools = getTools()
-    @test !isempty(registry_tools)
-    @test any(t -> t.name == "getTime", registry_tools)
-    @test any(t -> t.name == "getWeather", registry_tools)
-
-    clearTools()
-    @test isempty(getTools())
-
-    test_tool = agentTool(
-        name = "manualTool",
-        label = "Manual Tool",
-        description = "Registered manually",
-        inputSchema = Dict{String,Any}("type" => "object", "properties" => Dict{String,Any}(), "required" => Any[]),
-        execute = (toolCallId, args, signal, onPartialResult) ->
-            agentToolResult([textContent("manual")], Dict{Any,Any}(), nothing, false),
-        prepareArguments = nothing,
-        validateRequiredArgs = nothing,
-        parallelToolExecute = true
-    )
-    registerTool(test_tool)
-    reg = getTools()
-    @test any(t -> t.name == "manualTool", reg)
-    @test count(t -> t.name == "manualTool", reg) == 1
-    @test reg[1].parallelToolExecute == true
-
-    # ------------------------------------------------------------------ #
-    # 8. getTools returns deep copy (mutations don't affect registry)    #
-    # ------------------------------------------------------------------ #
-    copy1 = getTools()
-    copy2 = getTools()
-    @test copy1 !== copy2
-    empty!(copy1)
-    @test !isempty(getTools())
-end
@@ -1,401 +1,5 @@
-using JSON, Dates, UUIDs, PrettyPrinting, LibPQ, Base64, DataFrames, DataStructures, HTTP, Base64,
-      NATS, Base.Threads
-using YiemAgent, GeneralUtils, msghandler
-
-  function text2text_instruct_llm(sender_id::String, openai_msg::Dict{String, Any})
-    payloads = [("msg", openai_msg, "dictionary")]  # List of tuples
-    _, msg_envelope_json_str = msghandler.smartpack(
-          config["externalservice"]["servicesloadbalancer"]["nats"], 
-          payloads;
-          sender_id=sender_id,
-          msg_purpose="text2text",  
-          broker_url=config["nats_server_info"]["url"],
-          fileserver_url=config["externalservice"]["fileserver"]["url"])
-
-    reply = NATS.request(agent_conn, 
-                        config["externalservice"]["servicesloadbalancer"]["nats"], 
-                        msg_envelope_json_str, timeout=120)
-
-    incoming_env_json_str = String(reply.payload)
-    incoming_env = msghandler.smartunpack(incoming_env_json_str)
-    _llm_response = incoming_env["payloads"][1][2]
-    llm_response = _llm_response["choices"][1]["message"]["content"]
-    return llm_response
-  end
-
-  """ get a single text embedding from a LLM service
-  Example
-  text = ["hello"]
-  embedding = get_embedding(text)
-  """
-  function get_embedding(text::AbstractArray{String})
-    documents_dict = Dict("documents" => text)
-    payloads = [("documents", documents_dict, "dictionary")]
-    _, msg_envelope_json_str = msghandler.smartpack(
-      config["externalservice"]["servicesloadbalancer"]["nats"], 
-      payloads;   
-      msg_purpose="embedding",  
-      broker_url=config["nats_server_info"]["url"],
-      fileserver_url=config["externalservice"]["fileserver"]["url"])
-
-    reply = NATS.request(agent_conn, 
-                        config["externalservice"]["servicesloadbalancer"]["nats"], 
-                        msg_envelope_json_str, timeout=120)
-    incoming_env_json_str = String(reply.payload)
-    incoming_env = msghandler.smartunpack(incoming_env_json_str)
-    embedding_response = incoming_env["payloads"][1][2]
-
-    return embedding_response
-  end
-
-  """ sql = "SELECT * FROM wine;"
-  result = execute_sql_winedb(sql)
-  """
-  function execute_sql_winedb(sql::T) where {T<:AbstractString}
-    host_url, _port = split(config["externalservice"]["sommpanion_db"]["url"], ':')
-    port = parse(Int, _port)
-    dbname = "winedb"
-    user = config["externalservice"]["sommpanion_db"]["user"]
-    password = config["externalservice"]["sommpanion_db"]["password"]
-    db_connection = LibPQ.Connection("host=$host_url port=$port dbname=$dbname user=$user password=$password")
-    result = nothing
-    try
-      result = LibPQ.execute(db_connection, sql)  
-    catch e
-      LibPQ.close(db_connection)
-    end
-    
-    LibPQ.close(db_connection)
-    return result
-  end
-
-  """ find similar sql from vector database
-  sql = "SELECT * FROM wine;"
-  result, distance = similar_sql_vectordb(sql)
-  """
-  function similar_sql_vectordb(sql::T; maxdistance::Number=0.2) where {T<:AbstractString}
-    tablename = "sqlllm_decision_repository"
-    # get embedding of the query
-    df = find_similar_text_from_vectordb(sql, tablename, 
-          "function_input_embedding", execute_sql_vectordb)
-    # println(df[1, [:id, :function_output]])
-    row, col = size(df)
-    distance = row == 0 ? Inf : df[1, :distance]  
-    if row != 0 && distance < maxdistance
-      # if there is usable SQL, return it.
-      output_b64 = df[1, :function_output_base64]   # pick the closest match
-      output_str = String(base64decode(output_b64))
-      rowid = df[1, :id]
-      println("\n--| similar sql found. row id $rowid, distance $distance ", @__FILE__, ":", @__LINE__, " $(Dates.now())")
-      pprintln(output_str)
-      return (result=output_str, distance=distance)
-    else
-      println("\n--| similar sql not found, max distance $maxdistance ", @__FILE__, ":", @__LINE__, " $(Dates.now())")
-      return (result=nothing, distance=nothing)
-    end
-  end
-
-  """ insert query and sql into vector database
-  query = "get all wines from wine table"
-  sql = "SELECT * FROM wine;"
-  insert_sql_vectordb(query, sql)
-  """
-  function insert_sql_vectordb(query::T1, SQL::T2; maxdistance::Number=3
-    ) where {T1<:AbstractString, T2<:AbstractString}
-    
-    tablename = "sqlllm_decision_repository"
-    # get embedding of the query
-    # query = state[:thoughtHistory][:question]
-    df = find_similar_text_from_vectordb(query, tablename, 
-                                    "function_input_embedding", execute_sql_vectordb)
-    row, col = size(df)
-    distance = row == 0 ? Inf : df[1, :distance]
-    if row == 0 || distance > maxdistance # no close enough SQL stored in the database
-      _query_embedding = get_embedding([query])
-      _query_embedding = GeneralUtils.dictify(_query_embedding)
-      # println("\n--- _query_embedding() ", @__FILE__, ":", @__LINE__, " $(Dates.now())")
-      # println(_query_embedding)
-      # println("---\n")
-      query_embedding = _query_embedding["data"][1]["embedding"]
-      query = replace(query, "'" => "")
-      sql_base64 = base64encode(SQL)
-      sql_ = replace(SQL, "'" => "")
-
-      sql = 
-        """
-        INSERT INTO $tablename (function_input, function_output, function_output_base64, function_input_embedding) VALUES ('$query', '$sql_', '$sql_base64', '$query_embedding');
-        """
-      # println("\n--| added new decision to vectorDB ", @__FILE__, ":", @__LINE__, " $(Dates.now())")
-      # println(sql)
-      _ = execute_sql_vectordb(sql)
-    end
-  end
-
-  """ execute sql against vectordb
-  sql = "SELECT * FROM wine;"
-  result = execute_sql_vectordb(sql)
-  """
-  function execute_sql_vectordb(sql::T) where {T<:AbstractString}
-    host_url, _port = split(config["externalservice"]["sommpanion_vectordb"]["url"], ':')
-    port = parse(Int, _port)
-    dbname = config["externalservice"]["sommpanion_vectordb"]["dbname"]
-    user = config["externalservice"]["sommpanion_vectordb"]["user"]
-    password = config["externalservice"]["sommpanion_vectordb"]["password"]
-    DBconnection = LibPQ.Connection("host=$host_url port=$port dbname=$dbname user=$user password=$password")
-    result = LibPQ.execute(DBconnection, sql)
-    close(DBconnection)
-    return result
-  end
-
-  """ search similar decision llm made from vectordb
-  """
-  function similar_sommelier_decision(recentevents::T1; maxdistance::Integer=3
-    )::Union{AbstractDict, Nothing} where {T1<:AbstractString}
-
-    tablename = "sommelier_decision_repository"
-    # find similar
-    df = find_similar_text_from_vectordb(recentevents, tablename, 
-                                    "function_input_embedding", execute_sql_vectordb)
-    row, col = size(df)
-    distance = row == 0 ? Inf : df[1, :distance]
-    if row != 0 && distance < maxdistance
-      # if there is usable decision, return it.
-      rowid = df[1, :id]
-      println("\n--| found similar decision. row id $rowid, distance $distance ", @__FILE__, " ", @__LINE__)
-      output_b64 = df[1, :function_output_base64]   # pick the closest match
-      _output_str = String(base64decode(output_b64))
-      output = copy(JSON.read(_output_str))
-      return output
-    else
-      println("\n--| similar decision not found, max distance $maxdistance ", @__FILE__, " ", @__LINE__)
-      return nothing
-    end
-  end
-
-  """ search similar text from vectordb
-  """
-  function find_similar_text_from_vectordb(text::T1, tablename::T2, embeddingColumnName::T3,
-    vectorDB::Function; limit::Integer=1
-    )::DataFrame where {T1<:AbstractString, T2<:AbstractString, T3<:AbstractString}
-    # get embedding from LLM service
-    _embedding = get_embedding([text])
-    _embedding = _embedding["data"][1]["embedding"]
-    _embedding = "$_embedding"
-
-    embedding = _embedding[4:end]
-
-    # check whether there is close enough vector already store in vectorDB. if no, add, else skip 
-    sql = """
-          SELECT *, $embeddingColumnName <-> '$embedding' as distance
-          FROM $tablename
-          ORDER BY distance LIMIT $limit;
-          """
-    response = vectorDB(sql)
-    df = DataFrame(response)
-
-    return df
-  end
-
-  """ insert decision llm made to vectordb
-  """
-  function insert_sommelier_decision(recentevents::T1, decision::T2; maxdistance::Integer=5
-    ) where {T1<:AbstractString, T2<:AbstractDict}
-    tablename = "sommelier_decision_repository"
-    # find similar
-    df = find_similar_text_from_vectordb(recentevents, tablename, 
-                                    "function_input_embedding", execute_sql_vectordb)
-    row, col = size(df)
-    distance = row == 0 ? Inf : df[1, :distance]
-    if row == 0 || distance > maxdistance # no close enough SQL stored in the database
-      _embedding = get_embedding([recentevents])[1]
-      recentevents_embedding = _embedding["data"][1]["embedding"]
-      recentevents = replace(recentevents, "'" => "")
-      decision_json = JSON.json(decision)
-      decision_base64 = base64encode(decision_json)
-      decision = replace(decision_json, "'" => "")
-      
-      sql = 
-      """
-      INSERT INTO $tablename (function_input, function_output, function_output_base64, function_input_embedding) VALUES ('$recentevents', '$decision', '$decision_base64', '$recentevents_embedding');
-      """
-      println("\n--| added new decision to vectorDB ", @__FILE__, " ", @__LINE__)
-      println(sql)
-      _ = execute_sql_vectordb(sql)
-    else
-      println("--| similar decision previously cached, distance $distance ", @__FILE__, " ", @__LINE__)
-    end
-  end
-
-config = JSON.parsefile("./appconfig.json")
-sessionId = "0"
-backend_session_topic = "sommpanion.testsubject"
-agent_ch = Channel(8)
-agent_conn  = NATS.connect(config["nats_server_info"]["url"])
-
-sub2 = NATS.subscribe(agent_conn, backend_session_topic) do msg
-  put!(agent_ch, msg)
-end
-
-agent_context = YiemAgent.agentcontext(
-    text2text_instruct_llm,
-    get_embedding,
-    execute_sql_winedb,
-    similar_sql_vectordb,
-    insert_sql_vectordb,
-    similar_sommelier_decision,
-    insert_sommelier_decision
-  )
-
-  # can't instantiate
-  agent = YiemAgent.sommelier(
-    agent_context;
-    name="Janie",
-    id=sessionId,  # agent instance id
-    retailername="Yiem Wine Ltd.",
-    llmFormatName=""
-  )
-
-
-image1_path = "test/large_image.png"
-image1_bytes = read(image1_path)
-image1_base64_string = base64encode(image1_bytes)
-mime_type = "image/png" 
-data1_uri = "data:$(mime_type);base64,$(image1_base64_string)"
-
-# 1. Read local file and encode to base64 string
-image2_path = "test/small_image.png"
-image2_bytes = read(image2_path)
-image2_base64_string = base64encode(image2_bytes)
-mime_type = "image/png" 
-data2_uri = "data:$(mime_type);base64,$(image2_base64_string)"
-
-# 3. Construct payload with the Data URI
-message = Dict(
-    "role" => "user",
-    "content" => [
-      Dict("type" => "text", "text" => "Do you know type of wine in the image?"),
-      Dict(
-        "type" => "image_url",
-        "image_url" => Dict("url" => data1_uri)
-      )
-    ]
-  )
-
-result = YiemAgent.conversation(agent; userinput=message)
-println("\n$result")
-
-
-
-
-
-
-
-
-
-# message = Dict(
-#     "role" => "user",
-#     "content" => [
-#       Dict("type" => "text", "text" => 
-#       "
-#       เป็นงานเลี้ยงทั่วไป
-#       "),
-#     ]
-#   )
-
-# result = YiemAgent.conversation(agent; userinput=message)
-# println("\n$result")
-
-
-
-
-
-
-
-
-
-# message = Dict(
-#     "role" => "user",
-#     "content" => [
-#       Dict("type" => "text", "text" => "no thanks. that's all"),
-#     ]
-#   )
-
-# result = YiemAgent.conversation(agent; userinput=message)
-# println("\n$result")
-
-
-
-
-
-
-# message = Dict(
-#     "role" => "user",
-#     "content" => [
-#       Dict("type" => "text", "text" => "What about this wine?"),
-#       Dict(
-#         "type" => "image_url",
-#         "image_url" => Dict("url" => data2_uri)
-#       )
-#     ]
-#   )
-
-# result = YiemAgent.conversation(agent; userinput=message)
-# println("\n$result")
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+using Test
+using YiemAgent

+include("toolTest.jl")
+include("_extractToolCalls.jl")
@@ -0,0 +1,367 @@
+using Test
+using Dates
+using YiemAgent
+using YiemAgent.toolRegistry
+using YiemAgent.type
+using YiemAgent.agentCore
+
+@testset "register_all_tools with toolStore" begin
+
+    # ------------------------------------------------------------------ #
+    # 1. register_all_tools registers all static tools + listTools       #
+    # ------------------------------------------------------------------ #
+    store = toolStore(name="test1")
+    loaded = register_all_tools(store)
+    @test !isempty(loaded)
+    @test length(loaded) == 4  # getWeather + getTime + writeTool + listTools
+
+    names = [k for k in keys(loaded)]
+    @test "getTime" in names
+    @test "getWeather" in names
+    @test "writeTool" in names
+    @test "listTools" in names
+
+    # ------------------------------------------------------------------ #
+    # 2. register_all_tools returns tools in registration order          #
+    # ------------------------------------------------------------------ #
+    @test collect(keys(loaded))[1] == "getWeather"
+    @test collect(keys(loaded))[2] == "getTime"
+    @test collect(keys(loaded))[3] == "writeTool"
+    @test collect(keys(loaded))[4] == "listTools"
+
+    # ------------------------------------------------------------------ #
+    # 3. Verify loaded tool fields are correct                           #
+    # ------------------------------------------------------------------ #
+    # getTime
+    time_tool = loaded["getTime"]
+    @test time_tool.name == "getTime"
+    @test time_tool.label == "Time Lookup"
+    @test time_tool.validateRequiredArgs !== nothing
+    @test time_tool.parallelToolExecute == false
+    @test time_tool.inputSchema["required"] == Any[]
+
+    # getWeather
+    weather = loaded["getWeather"]
+    @test weather.name == "getWeather"
+    @test weather.label == "Weather Lookup"
+    @test weather.execute !== nothing
+    @test weather.parallelToolExecute == false
+    @test weather.inputSchema["required"] == ["city"]
+
+    # writeTool
+    wt = loaded["writeTool"]
+    @test wt.name == "writeTool"
+    @test wt.label == "Create Tool"
+    @test wt.execute !== nothing
+    @test "name" in wt.inputSchema["required"]
+    @test "executeCode" in wt.inputSchema["required"]
+
+    # ------------------------------------------------------------------ #
+    # 4. Tool execution returns valid results                            #
+    # ------------------------------------------------------------------ #
+    sig = nothing
+    op = x -> x  # no-op partial result callback
+
+    # execute getTime
+    result_t = time_tool.execute("call-1", Dict{String,Any}("city" => "Tokyo"), sig, op)
+    @test result_t isa agentToolResult
+    @test result_t.content[1] isa textContent
+    @test occursin("Tokyo", result_t.content[1].text)
+
+    # execute getTime with timezone
+    result_tz = time_tool.execute("call-2", Dict{String,Any}("timezone" => "America/New_York"), sig, op)
+    @test result_tz isa agentToolResult
+    @test occursin("America/New_York", result_tz.content[1].text)
+
+    # execute getWeather
+    result_w = weather.execute("call-3", Dict{String,Any}("city" => "Bangkok"), sig, op)
+    @test result_w isa agentToolResult
+    @test result_w.content[1] isa textContent
+    @test occursin("Bangkok", result_w.content[1].text)
+
+    # execute getWeather with units
+    result_w2 = weather.execute("call-4", Dict{String,Any}("city" => "London", "units" => "fahrenheit"), sig, op)
+    @test occursin("72\u00b0F", result_w2.content[1].text)
+
+    # ------------------------------------------------------------------ #
+    # 5. getTools / registerTool / clearTools (per-store isolation)      #
+    # ------------------------------------------------------------------ #
+    store3 = toolStore(name="test3")
+    registry_tools = getTools(store3)
+    @test isempty(registry_tools)
+
+    # Register tools manually
+    registerTool(store3, loaded["getTime"])
+    registerTool(store3, loaded["getWeather"])
+    registerTool(store3, loaded["writeTool"])
+
+    reg = getTools(store3)
+    @test !isempty(reg)
+    @test "getTime" in keys(reg)
+    @test "getWeather" in keys(reg)
+    @test "writeTool" in keys(reg)
+    @test collect(keys(reg))[1] == "getTime"
+    @test collect(keys(reg))[2] == "getWeather"
+    @test collect(keys(reg))[3] == "writeTool"
+
+    clearTools(store3)
+    @test isempty(getTools(store3))
+
+    test_tool = agentTool(
+        name = "manualTool",
+        label = "Manual Tool",
+        description = "Registered manually",
+        inputSchema = Dict{String,Any}("type" => "object", "properties" => Dict{String,Any}(), "required" => Any[]),
+        execute = (toolCallId, args, signal, onPartialResult) ->
+            agentToolResult([textContent("manual")], Dict{Any,Any}(), nothing, false),
+        prepareArguments = nothing,
+        validateRequiredArgs = nothing,
+        parallelToolExecute = true
+    )
+    registerTool(store3, test_tool)
+    reg = getTools(store3)
+    @test haskey(reg, "manualTool")
+    @test length(reg) == 1
+    @test reg["manualTool"].parallelToolExecute == true
+
+    # ------------------------------------------------------------------ #
+    # 6. getTools returns direct reference (mutations affect registry)   #
+    # ------------------------------------------------------------------ #
+    copy1 = getTools(store3)
+    copy2 = getTools(store3)
+    @test copy1 === copy2  # same reference, not a deep copy
+    empty!(copy1)
+    @test isempty(getTools(store3))  # mutation propagates
+
+    # ------------------------------------------------------------------ #
+    # 7. Per-store isolation — two stores don't share tools              #
+    # ------------------------------------------------------------------ #
+    storeA = toolStore(name="isolationA")
+    storeB = toolStore(name="isolationB")
+
+    registerTool(storeA, loaded["getTime"])
+    registerTool(storeB, loaded["getWeather"])
+
+    regA = getTools(storeA)
+    regB = getTools(storeB)
+
+    @test "getTime" in keys(regA)
+    @test "getWeather" ∉ keys(regA)
+    @test "getWeather" in keys(regB)
+    @test "getTime" ∉ keys(regB)
+
+    clearTools(storeA)
+    @test isempty(getTools(storeA))
+    @test !isempty(getTools(storeB))  # storeB unaffected
+end
+
+@testset "listTool" begin
+    store = toolStore(name="test_list")
+    register_all_tools(store)  # auto-registers getWeather, getTime, writeTool + listTools
+
+    # register_all_tools auto-registers listTool
+    @test "listTools" in keys(store.tools)
+
+    # listTool returns an agentTool, not a string or array
+    list_t = listTool(store)
+    @test list_t isa agentTool
+    @test list_t.name == "listTools"
+    @test list_t.label == "List Tools"
+    @test isempty(list_t.inputSchema["required"])
+
+    # Verify all tools appear (3 loaded + listTools = 4)
+    result = list_t.execute("call-1", Dict{String,Any}(), nothing, x -> x)
+    @test result isa agentToolResult
+    @test result.content[1] isa textContent
+    @test occursin("listTools", result.content[1].text)
+    @test occursin("getWeather", result.content[1].text)
+    @test occursin("getTime", result.content[1].text)
+    @test occursin("writeTool", result.content[1].text)
+    @test result.details["count"] == 4
+
+    # Each listTool call creates an independent closure
+    storeB = toolStore(name="test_listB")
+    registerTool(storeB, store.tools["getWeather"])
+    list_tB = listTool(storeB)
+
+    resultA = list_t.execute("call-3", Dict{String,Any}(), nothing, x -> x)
+    resultB = list_tB.execute("call-4", Dict{String,Any}(), nothing, x -> x)
+
+    @test occursin("getWeather", resultA.content[1].text)
+    @test occursin("getWeather", resultB.content[1].text)
+    @test occursin("getTime", resultA.content[1].text)
+    @test occursin("getTime", resultB.content[1].text) == false  # storeB only has getWeather
+end
+
+@testset "executePreparedToolCall with static tools" begin
+    # Tests executePreparedToolCall with statically loaded tools.
+    # The world-age issue is resolved because tool.execute comes from
+    # a statically included module, not a dynamically created one.
+
+    store = toolStore(name="test_static")
+    register_all_tools(store)
+
+    weather_tool = store.tools["getWeather"]
+
+    # Create a preparedToolCall that mimics what prepareToolCall() returns
+    tool_call = agentToolCall(
+        "function", "call-static-1", "getWeather",
+        Dict{String,Any}("city" => "San Francisco")
+    )
+    prep = preparedToolCall(
+        weather_tool, tool_call, Dict{String,Any}("city" => "San Francisco")
+    )
+    sig = abortSignal(false)
+
+    # This call goes through: executePreparedToolCall -> prep.tool.execute(...)
+    result = executePreparedToolCall(
+        prep, sig, x -> nothing
+    )
+
+    @test result isa executedOutcome
+    @test result.isError == false
+    @test result.result.content[1] isa textContent
+    @test occursin("San Francisco", result.result.content[1].text)
+end
+
+@testset "executePreparedToolCall with validation (static tools)" begin
+    # Tests executePreparedToolCall with a tool that has custom validation hooks.
+    # This exercises the full tool execution path including validation.
+
+    store = toolStore(name="test_static_validate")
+    register_all_tools(store)
+
+    time_tool = store.tools["getTime"]
+
+    tool_call = agentToolCall(
+        "function", "call-static-2", "getTime",
+        Dict{String,Any}("timezone" => "America/New_York")
+    )
+    prep = preparedToolCall(
+        time_tool, tool_call, Dict{String,Any}("timezone" => "America/New_York")
+    )
+    sig = abortSignal(false)
+
+    result = executePreparedToolCall(
+        prep, sig, x -> nothing
+    )
+
+    @test result isa executedOutcome
+    @test result.isError == false
+    @test result.result.content[1] isa textContent
+    @test occursin("America/New_York", result.result.content[1].text)
+end
+
+@testset "executeToolCallsSequential with static tools (full pipeline)" begin
+    # Tests the full tool execution pipeline: executeToolCallsSequential
+    # which calls prepareToolCall -> executePreparedToolCall -> finalizeExecutedToolCall
+    # with statically loaded tools.
+
+    store = toolStore(name="test_full_pipeline")
+    register_all_tools(store)
+
+    # Build agentContext from the store's tools
+    tools = getTools(store)
+    ctx = agentContext(
+        "test system prompt",
+        agentMessage[],
+        tools
+    )
+
+    # Create an assistant message containing tool calls
+    assistant_msg = assistantMessage(
+        role="assistant",
+        content=Vector{messageContent}(),
+        api="openai",
+        provider="test",
+        model="test-model",
+        usage=llmUsage(0, 0),
+        stopReason="tool_calls",
+        errorMessage=nothing,
+        timestamp=now()
+    )
+
+    # Create tool calls for multiple statically loaded tools
+    tool_calls = [
+        agentToolCall(
+            "function", "call-seq-1", "getWeather",
+            Dict{String,Any}("city" => "Tokyo")
+        ),
+        agentToolCall(
+            "function", "call-seq-2", "getTime",
+            Dict{String,Any}("timezone" => "Europe/London")
+        ),
+    ]
+
+    config = agentLoopConfig(
+        nothing, nothing, "sequential"
+    )
+    sig = abortSignal(false)
+
+    # Execute the full pipeline
+    batch = executeToolCallsSequential(
+        ctx, assistant_msg, tool_calls, config, sig, x -> nothing
+    )
+
+    @test batch.messages isa Vector{toolResultMessage}
+    @test length(batch.messages) == 2
+    @test batch.messages[1].toolName == "getWeather"
+    @test batch.messages[1].isError == false
+    @test occursin("Tokyo", batch.messages[1].content[1].text)
+    @test batch.messages[2].toolName == "getTime"
+    @test batch.messages[2].isError == false
+    @test occursin("Europe/London", batch.messages[2].content[1].text)
+end
+
+@testset "executeToolCallsParallel with static tools (full pipeline)" begin
+    # Same as above but tests parallel execution path.
+
+    store = toolStore(name="test_parallel")
+    register_all_tools(store)
+
+    tools = getTools(store)
+    ctx = agentContext(
+        "test system prompt",
+        agentMessage[],
+        tools
+    )
+
+    assistant_msg = assistantMessage(
+        role="assistant",
+        content=Vector{messageContent}(),
+        api="openai",
+        provider="test",
+        model="test-model",
+        usage=llmUsage(0, 0),
+        stopReason="tool_calls",
+        errorMessage=nothing,
+        timestamp=now()
+    )
+
+    tool_calls = [
+        agentToolCall(
+            "function", "call-par-1", "getWeather",
+            Dict{String,Any}("city" => "Paris")
+        ),
+        agentToolCall(
+            "function", "call-par-2", "getTime",
+            Dict{String,Any}("city" => "Sydney")
+        ),
+    ]
+
+    config = agentLoopConfig(
+        nothing, nothing, "parallel"
+    )
+    sig = abortSignal(false)
+
+    batch = executeToolCallsParallel(
+        ctx, assistant_msg, tool_calls, config, sig, x -> nothing
+    )
+
+    @test batch.messages isa Vector{toolResultMessage}
+    @test length(batch.messages) == 2
+    @test batch.messages[1].toolName == "getWeather"
+    @test batch.messages[1].isError == false
+    @test batch.messages[2].toolName == "getTime"
+    @test batch.messages[2].isError == false
+end
@@ -0,0 +1,113 @@
+using Revise, JSON, Dates, UUIDs, PrettyPrinting, LibPQ, Base64, DataFrames, DataStructures, HTTP, Base64,
+      NATS, Base.Threads
+using YiemAgent, GeneralUtils, msghandler
+
+
+""" Debug 
+
+using JSON, NATS, msghandler
+using NATS
+
+conn = NATS.connect("nats.yiem.cc")
+
+sub = NATS.subscribe(conn, "sommanion.debug") do msg
+  payload = NATS.payload(msg)
+  @info "debug" payload
+
+  open("./log/error.log", "a") do io
+    println(io, payload)
+  end
+end
+
+NATS.publish(conn, "sommanion.debug", "order-123")
+
+
+# ---------------------------- inject this code into codebase to debug --------------------------- #
+try
+  batch = someFunction(x, y, z)
+catch e
+  bt = catch_backtrace()
+  err_msg = sprint() do io
+      showerror(io, e, bt)
+      println(io)
+  end
+
+  agentEventSink(err_msg)
+end
+
+"""
+
+struct text2textInstructLLM
+  natsConn::NATS.Connection
+  topic::String
+  senderID::String
+  fileserver_url::String
+end
+
+function (t::text2textInstructLLM)(openai_msg::Dict{String, Any})
+
+  payloads = [("msg", openai_msg, "dictionary")]  # List of tuples
+  _, msg_envelope_json_str = msghandler.smartpack(
+        t.topic, 
+        payloads;
+        sender_id=t.senderID,
+        msg_purpose="text2text",  
+        fileserver_url=t.fileserver_url)
+
+  reply = NATS.request(t.natsConn, t.topic, msg_envelope_json_str, timeout=180)
+
+  incoming_env_json_str = String(reply.payload)
+  incoming_env = msghandler.smartunpack(incoming_env_json_str)
+  _llm_response = incoming_env["payloads"][1][2]
+  llm_response = _llm_response["choices"][1]
+
+  return llm_response
+end
+
+
+
+struct agentEventSink
+  natsConn::NATS.Connection
+  topic::String
+  senderID::String
+end
+
+function (aes::agentEventSink)(msg::String)
+  NATS.publish(aes.natsConn, aes.topic, msg)
+end
+
+
+
+config = JSON.parsefile("./appconfig.json")
+agent_conn  = NATS.connect(config["nats_server_info"]["url"])
+
+
+#WORKING load tools
+text2text_llm = text2textInstructLLM(agent_conn, 
+                                    config["externalservice"]["servicesloadbalancer"]["nats"], 
+                                    "sender", 
+                                    config["externalservice"]["fileserver"]["url"])
+
+debugNats = agentEventSink(agent_conn, "sommanion.debug", "sender")
+
+agent = YiemAgent.yiemAgent(
+  text2text_llm;
+  agentEventSink=debugNats
+)
+
+msg = Dict(
+        "role" => "user",
+        "content" => [
+          Dict("type" => "text", "text" => "What's the weather in Bangkok?"),
+          # Dict(
+          #   "type" => "image_url",
+          #   "image_url" => Dict("url" => "data:mime_type;base64,image2_base64_string")
+          # ),
+        ]
+      )
+      
+push!(agent.inputChannel, msg)
+
+
+
+
Author	SHA1	Message	Date
ton	a29a82b74c	update	2026-08-16 13:36:01 +07:00
ton	fd616409dd	update	2026-08-15 20:03:01 +07:00
ton	2543e6cbf1	static tool loading	2026-08-15 16:50:28 +07:00
ton	b8067c2d33	update	2026-08-13 18:14:46 +07:00
ton	510cf6126c	update	2026-08-13 05:56:08 +07:00
ton	90fb97a4e7	update	2026-08-12 23:47:10 +07:00
ton	77adeb3a6b	update	2026-08-12 20:10:51 +07:00
ton	4e592173a6	update	2026-08-12 14:37:11 +07:00
ton	0cacb5c94a	update	2026-08-12 04:35:34 +07:00
ton	6c96409969	update	2026-08-12 04:33:19 +07:00
ton	06d51c1ee9	update	2026-08-12 04:00:09 +07:00
ton	2ad3d1df38	update	2026-08-11 19:10:37 +07:00
ton	83c7770877	update	2026-08-11 18:57:53 +07:00
ton	bad14fbe7f	update	2026-08-11 18:42:34 +07:00
ton	578e8f55bd	update	2026-08-11 18:28:03 +07:00
ton	ae3e432b02	update	2026-08-11 17:35:56 +07:00
ton	7c14390400	update	2026-08-11 17:28:25 +07:00
ton	89885c1583	update	2026-08-11 16:43:48 +07:00
ton	5a27630ccf	update	2026-08-11 12:15:05 +07:00
ton	ed91260468	update	2026-08-10 20:37:28 +07:00
ton	c13aeb3a74	Merge pull request 'V0.8.0 verify tool use' (#43 ) from v0.8.0-verify_tool_use into v0.8.0 Reviewed-on: #43	2026-08-10 13:10:57 +00:00
ton	287704778f	update	2026-08-10 20:07:15 +07:00
ton	a9fa23f01b	update	2026-08-10 19:19:58 +07:00
ton	c5cb18f0f1	update	2026-08-10 16:10:04 +07:00
ton	c78f4b023d	update	2026-08-10 14:55:09 +07:00
ton	1b69f69c7d	update	2026-08-10 13:33:45 +07:00
ton	3891099eaa	update readme	2026-08-10 10:39:30 +07:00
ton	268d340e2f	Merge pull request 'V0.8.0 use tool module' (#42 ) from v0.8.0-use_tool_module into v0.8.0 Reviewed-on: #42	2026-08-10 02:48:25 +00:00
ton	189bc2efcf	update	2026-08-10 09:43:35 +07:00
ton	92b3e4081f	update	2026-08-09 22:50:02 +07:00
ton	750eff483b	update	2026-08-09 22:08:04 +07:00