Skip to content

EN Course 00 Overview

Jump to bottom
lloydzhou edited this page Jun 1, 2026 · 2 revisions

Course Overview

This course explains bash-agent by rebuilding its architecture from a small Bash agent loop. The goal is not to teach every line of agent.sh at once. Each chapter adds one runtime capability and connects it back to the implementation.

Learning Outcomes

After finishing the course, you should be able to:

  • explain the end-to-end runtime path from user input to assistant output
  • map major runtime responsibilities to agent.sh sections
  • reason about long-session compaction as a cache-and-cost decision
  • understand tool dispatch boundaries, permission checks, and failure handling
  • use plan/todo/sub-agent mechanisms with correct lifecycle ordering
  • evaluate runtime parity requirements across Bash, C, Go, and Rust

Reading Path

  1. Minimal Agent Loop
    Accept user input, build a request, call the model, and print assistant text.

  2. Streaming Transport
    Read provider SSE streams and normalize text, thinking, usage, tool calls, and stop reasons.

  3. Message Protocol and Display
    Separate internal events from human rendering and stream-json output.

  4. Session Store
    Persist conversation, events, stats, plans, and summaries as durable session state.

  5. System Prompt Builder
    Compose instructions, skills, plans, summaries, environment metadata, and tool guidance.

  6. Compaction and Long Sessions
    Keep long sessions usable with cache-aligned summarization and dynamic compaction decisions.

  7. Tool Calling
    Convert model tool requests into dispatcher calls and persist tool results.

  8. Bash Tool Permission Mode
    Classify shell commands with system/external/network/workspace scopes and read/write/execute bits.

  9. Plan and Todo Workflow
    Separate draft plans, locked plans, and progress tracking so planning does not constantly invalidate the prompt cache.

  10. Sub-Agent Runtime
    Treat sub-agents as restricted child runtime instances that run the same agent loop and report results asynchronously.

  11. Runtime Parity
    Keep Bash, C, Go, and Rust implementations aligned at the behavioral boundary.

Chapter Completion Criteria

Use this as a lightweight self-check after each chapter:

  • Chapter 01: can describe one full request/response loop
  • Chapter 02: can explain streamed event normalization
  • Chapter 03: can distinguish protocol events from display rendering
  • Chapter 04: can name persisted session artifacts and why they matter
  • Chapter 05: can explain prompt section composition and ordering
  • Chapter 06: can explain when and why compaction should happen
  • Chapter 07: can trace model tool calls to runtime execution and persisted results
  • Chapter 08: can reason about permission classification outcomes
  • Chapter 09: can apply draft/confirm/execute/clear lifecycle correctly
  • Chapter 10: can explain async child result injection and parent follow-up turn
  • Chapter 11: can articulate parity boundaries across runtimes

If you can complete these checks, you can read and modify the runtime with predictable behavior impact.

Reference Implementation Map

The Bash runtime is the reference implementation. Its major sections map directly to the course:

agent.sh Section Course Area
util_* message framing, escaping, prompt sections
store_* sessions, events, stats, plans, summaries
llm_* transport and provider calls
tool_* tool schema, dispatch, result formatting
display_* human display and stream events
agent_* prompt building, loop control, compaction, sub-agents
cli configuration and interactive mode

Existing Design Notes

The course introduces concepts in order. The design notes keep deeper explanations for specific subsystems:

Clone this wiki locally