diff --git a/docs/Codex/03_agent_loop.md b/docs/Codex/03_agent_loop.md index f4427f7..f2f1860 100644 --- a/docs/Codex/03_agent_loop.md +++ b/docs/Codex/03_agent_loop.md @@ -35,9 +35,9 @@ The Agent Loop is responsible for: * A request to perform an action (a "function call"): "I need to run this command: `python -c 'print(\"hello world\")'`" 4. Showing you the text part of the response in the [Terminal UI](01_terminal_ui__ink_components_.md). 5. Handling the "function call": - * Checking if it needs your permission based on the [Approval Policy](04_approval_policy___security_.md). + * Checking if it needs your permission based on the [Approval Policy](04_approval_policy___security.md). * If needed, asking you "Allow command?" via the UI. - * If approved, actually running the command using the [Command Execution & Sandboxing](06_command_execution___sandboxing_.md) system. + * If approved, actually running the command using the [Command Execution & Sandboxing](06_command_execution___sandboxing.md) system. 6. Getting the result of the command (the output "hello world"). 7. Sending that result back to the AI ("I ran the command, and it printed 'hello world'"). 8. Getting the AI's final response (maybe: "Great, the script ran successfully!"). @@ -76,11 +76,11 @@ graph TD 1. **Input:** Gets input from you (via the [Input Handling](02_input_handling__textbuffer_editor_.md)). 2. **AI Call:** Sends the current conversation state (including your latest input and any previous steps) to the AI model (OpenAI API). -3. **Response Processing:** Receives the AI's response. This could be simple text, or it could include a request to use a tool (like running a shell command). This is covered more in [Response & Tool Call Handling](05_response___tool_call_handling_.md). +3. **Response Processing:** Receives the AI's response. This could be simple text, or it could include a request to use a tool (like running a shell command). This is covered more in [Response & Tool Call Handling](05_response___tool_call_handling.md). 4. **Tool Handling:** If the AI requested a tool: - * Check the [Approval Policy](04_approval_policy___security_.md). + * Check the [Approval Policy](04_approval_policy___security.md). * Potentially ask you for confirmation via the [Terminal UI](01_terminal_ui__ink_components_.md). - * If approved, execute the tool via [Command Execution & Sandboxing](06_command_execution___sandboxing_.md). + * If approved, execute the tool via [Command Execution & Sandboxing](06_command_execution___sandboxing.md). * Package the tool's result (e.g., command output) to send back to the AI in the next step. 5. **Update State:** Adds the AI's message and any tool results to the conversation history. Shows updates in the UI. 6. **Loop:** If the task isn't finished (e.g., because a tool was used and the AI needs to react to the result), it sends the updated conversation back to the AI (Step 2). If the task *is* finished, it waits for your next input. @@ -320,7 +320,7 @@ export class AgentLoop { * If a tool call is found, it calls `handleFunctionCall`. * **`handleFunctionCall()`:** * Parses the details of the tool request (e.g., the command arguments). - * Uses `handleExecCommand` (which contains logic related to [Approval Policy](04_approval_policy___security_.md) and [Command Execution](06_command_execution___sandboxing_.md)) to potentially run the command, using the `getCommandConfirmation` callback if needed. + * Uses `handleExecCommand` (which contains logic related to [Approval Policy](04_approval_policy___security.md) and [Command Execution](06_command_execution___sandboxing.md)) to potentially run the command, using the `getCommandConfirmation` callback if needed. * Formats the result of the tool execution (e.g., command output) into a specific `function_call_output` message. * Returns this output message. The `run` method adds this to `turnInput`, so the *next* iteration of the `while` loop will send this result back to the AI, letting it know what happened. * **Finally:** Once the `while` loop finishes (meaning the AI didn't request any more tools in its last response), it signals loading is done (`onLoading(false)`). @@ -329,11 +329,11 @@ This loop ensures that the conversation flows logically, handling text, tool req ## Conclusion -The Agent Loop is the central orchestrator within Codex. It acts like a diligent assistant, taking your requests, interacting with the powerful AI model, managing tools like shell commands, ensuring safety through approvals, and keeping the conversation state updated. It connects the [Terminal UI](01_terminal_ui__ink_components_.md) where you interact, the [Input Handling](02_input_handling__textbuffer_editor_.md) that captures your text, the AI model that provides intelligence, and the systems that actually execute actions ([Command Execution & Sandboxing](06_command_execution___sandboxing_.md)). +The Agent Loop is the central orchestrator within Codex. It acts like a diligent assistant, taking your requests, interacting with the powerful AI model, managing tools like shell commands, ensuring safety through approvals, and keeping the conversation state updated. It connects the [Terminal UI](01_terminal_ui__ink_components_.md) where you interact, the [Input Handling](02_input_handling__textbuffer_editor_.md) that captures your text, the AI model that provides intelligence, and the systems that actually execute actions ([Command Execution & Sandboxing](06_command_execution___sandboxing.md)). Understanding the Agent Loop helps you see how Codex manages the complex back-and-forth required to turn your natural language requests into concrete actions. But when the Agent Loop wants to run a command suggested by the AI, how does Codex decide whether to ask for your permission first? That crucial safety mechanism is the topic of our next chapter. -Next up: [Approval Policy & Security](04_approval_policy___security_.md) +Next up: [Approval Policy & Security](04_approval_policy___security.md) --- diff --git a/docs/Codex/05_response___tool_call_handling.md b/docs/Codex/05_response___tool_call_handling.md index 47aeb11..1900d5e 100644 --- a/docs/Codex/05_response___tool_call_handling.md +++ b/docs/Codex/05_response___tool_call_handling.md @@ -7,7 +7,7 @@ nav_order: 5 # Chapter 5: Response & Tool Call Handling -In the [previous chapter](04_approval_policy___security_.md), we learned how Codex decides *if* it's allowed to perform an action suggested by the AI, acting like a security guard based on the rules you set. But how does Codex understand the AI's response in the first place, especially when the AI wants to do something specific, like run a command or change a file? +In the [previous chapter](04_approval_policy___security.md), we learned how Codex decides *if* it's allowed to perform an action suggested by the AI, acting like a security guard based on the rules you set. But how does Codex understand the AI's response in the first place, especially when the AI wants to do something specific, like run a command or change a file? That's where **Response & Tool Call Handling** comes in. Think of this part of Codex as its "ears" and "hands." It listens carefully to the instructions coming back from the AI model (the "response") and, if the AI asks to perform an action (a "tool call"), it figures out *exactly* what the AI wants to do (like which command to run or what file change to make) and gets ready to do it. @@ -97,7 +97,7 @@ sequenceDiagram * The **tool name** (e.g., `shell`) is identified. * The **arguments** string is extracted. * The arguments string (which is often JSON) is parsed to get the actual details (e.g., the `command` array `["git", "status"]`). -5. **Prepare for Action:** The Agent Loop now knows the specific tool and its arguments. It packages this information (tool name + parsed arguments) and prepares for the next stage: checking the [Approval Policy & Security](04_approval_policy___security_.md) and, if approved, proceeding to [Command Execution & Sandboxing](06_command_execution___sandboxing_.md). +5. **Prepare for Action:** The Agent Loop now knows the specific tool and its arguments. It packages this information (tool name + parsed arguments) and prepares for the next stage: checking the [Approval Policy & Security](04_approval_policy___security.md) and, if approved, proceeding to [Command Execution & Sandboxing](06_command_execution___sandboxing.md). ## Under the Hood: Parsing the Details @@ -189,7 +189,7 @@ private async handleFunctionCall(item: ResponseFunctionToolCall): Promise; Single-Pass Mode offers a different, potentially faster way to use Codex for well-defined tasks. By providing extensive context upfront and asking the AI for a complete set of structured file operations in one response, it minimizes back-and-forth. You gather context, send one big request, review the complete proposed solution, and either accept or reject it entirely. While still experimental, it's a powerful approach for streamlining larger refactoring or generation tasks where the requirements are clear. -This concludes our tour through the core concepts of Codex! We've journeyed from the [Terminal UI](01_terminal_ui__ink_components_.md) and [Input Handling](02_input_handling__textbuffer_editor_.md), through the central [Agent Loop](03_agent_loop.md), into the crucial aspects of [Approval Policy & Security](04_approval_policy___security_.md), [Response & Tool Call Handling](05_response___tool_call_handling.md), and safe [Command Execution & Sandboxing](06_command_execution___sandboxing.md), learned about [Configuration Management](07_configuration_management.md), and finally explored the alternative [Single-Pass Mode](08_single_pass_mode.md). +This concludes our tour through the core concepts of Codex! We've journeyed from the [Terminal UI](01_terminal_ui__ink_components_.md) and [Input Handling](02_input_handling__textbuffer_editor_.md), through the central [Agent Loop](03_agent_loop.md), into the crucial aspects of [Approval Policy & Security](04_approval_policy___security.md), [Response & Tool Call Handling](05_response___tool_call_handling.md), and safe [Command Execution & Sandboxing](06_command_execution___sandboxing.md), learned about [Configuration Management](07_configuration_management.md), and finally explored the alternative [Single-Pass Mode](08_single_pass_mode.md). We hope this gives you a solid understanding of how Codex works under the hood. Feel free to dive deeper into the codebase, experiment, and perhaps even contribute!