mirror of
https://github.com/outbackdingo/optimclaw.git
synced 2026-08-25 14:53:34 +00:00
OutBack Dingo
6d9dbbb3b9
Full rename of all identifiers, filenames, and references: ironclaw → optimclaw IronClaw → OptimClaw IRONCLAW → OPTIMCLAW ironclaw_common → optimclaw_common ironclaw_safety → optimclaw_safety Upstream: nearai/ironclaw
90 lines
4.2 KiB
Markdown
90 lines
4.2 KiB
Markdown
---
|
|
description: Trace a data flow or bug through the OptimClaw codebase end-to-end
|
|
allowed-tools: Read, Glob, Grep, Bash(cargo test:*)
|
|
argument-hint: <symptom or feature name>
|
|
model: sonnet
|
|
---
|
|
|
|
Trace the flow of `$ARGUMENTS` through the OptimClaw codebase. Your job is to map every file and function involved, identify where data transforms or could break, and report the full chain.
|
|
|
|
## Architecture Reference
|
|
|
|
OptimClaw has three main data flow paths. Identify which one(s) are relevant and trace through them:
|
|
|
|
### Message Flow (user input to LLM response)
|
|
```
|
|
Channel (cli/web/wasm) → IncomingMessage
|
|
→ Agent::run() message loop (agent_loop.rs)
|
|
→ handle_message() dispatches by Submission type
|
|
→ SubmissionParser::parse() (submission.rs) classifies input
|
|
→ process_user_input() for new turns
|
|
→ process_approval() for tool approval responses
|
|
→ handle_command() for /commands
|
|
→ run_agentic_loop() iterates LLM calls
|
|
→ Reasoning::respond_with_tools() (reasoning.rs)
|
|
→ LlmProvider::complete_with_tools() (nearai_chat.rs or nearai.rs)
|
|
→ Tool execution with approval gating
|
|
→ Context message accumulation
|
|
→ Response flows back through Channel::send_response()
|
|
```
|
|
|
|
### SSE Event Flow (backend status to web UI)
|
|
```
|
|
StatusUpdate variant (channel.rs)
|
|
→ Channel::send_status() trait method
|
|
→ WebChannel::send_status() (web/mod.rs) maps to SseEvent
|
|
→ broadcast via tokio::broadcast channel
|
|
→ SSE endpoint streams events (web/server.rs)
|
|
→ Browser EventSource listener (app.js)
|
|
→ DOM update function
|
|
→ CSS styling (style.css)
|
|
```
|
|
|
|
### Tool Flow (tool definition to execution)
|
|
```
|
|
Tool trait impl (tools/builtin/*.rs or tools/mcp/client.rs or tools/wasm/wrapper.rs)
|
|
→ ToolRegistry::register() (tools/registry.rs)
|
|
→ tool_definitions() builds Vec<ToolDefinition> for LLM
|
|
→ ToolDefinition { name, description, parameters } (llm/provider.rs)
|
|
→ Serialized to ChatCompletionTool (nearai_chat.rs)
|
|
→ LLM returns ToolCall { id, name, arguments }
|
|
→ agent_loop.rs executes via execute_chat_tool()
|
|
→ Safety layer sanitizes output
|
|
→ Result added as ChatMessage::tool_result()
|
|
```
|
|
|
|
## Tracing Instructions
|
|
|
|
1. **Read** each file in the relevant flow path, focusing on the functions that handle the data.
|
|
2. **Identify transforms**: Where does the data change shape? (e.g., `McpTool.input_schema` → `ToolDefinition.parameters` → `ChatCompletionTool.function.parameters`)
|
|
3. **Identify failure points**: Where could the data be lost, malformed, or misrouted?
|
|
4. **Report the chain**: List every file:line involved, what happens at each step, and where the issue (if any) is.
|
|
|
|
## Key Files Quick Reference
|
|
|
|
| Area | File | Key Functions |
|
|
|------|------|---------------|
|
|
| Message dispatch | `src/agent/agent_loop.rs` | `handle_message`, `process_user_input`, `process_approval`, `run_agentic_loop` |
|
|
| Input parsing | `src/agent/submission.rs` | `SubmissionParser::parse` |
|
|
| LLM reasoning | `src/llm/reasoning.rs` | `respond_with_tools`, `select_tools`, `plan` |
|
|
| Chat completions | `src/llm/nearai_chat.rs` | `complete_with_tools`, `From<ChatMessage>` |
|
|
| Responses API | `src/llm/nearai.rs` | `complete_with_tools`, `split_messages` |
|
|
| Channel trait | `src/channels/channel.rs` | `Channel`, `StatusUpdate`, `IncomingMessage` |
|
|
| Web gateway | `src/channels/web/mod.rs` | `send_status`, `send_response` |
|
|
| Web server | `src/channels/web/server.rs` | Route handlers, SSE endpoints |
|
|
| Web frontend | `src/channels/web/static/app.js` | SSE listeners, DOM builders |
|
|
| Tool registry | `src/tools/registry.rs` | `tool_definitions`, `get`, `register` |
|
|
| MCP tools | `src/tools/mcp/client.rs` | `McpToolWrapper`, `list_tools`, `call_tool` |
|
|
| MCP protocol | `src/tools/mcp/protocol.rs` | `McpTool`, `inputSchema` |
|
|
| Safety | `src/safety/sanitizer.rs` | `sanitize_tool_output`, `wrap_for_llm` |
|
|
| Session state | `src/agent/session.rs` | `ThreadState`, `Turn`, `PendingApproval` |
|
|
|
|
## Output Format
|
|
|
|
Report your findings as:
|
|
|
|
1. **Flow path**: The specific chain of files and functions involved
|
|
2. **Data transforms**: How the data changes at each step
|
|
3. **Findings**: Any bugs, missing data, or suspicious patterns
|
|
4. **Recommendation**: What to fix or investigate further
|