lkn
/
ollie
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add debugging lessons learned from session

This commit is contained in:
Levi Neely 2026-08-17 13:47:51 +02:00
parent 025c351dcb
commit 9aa29c156c
1 changed files with 8 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
AGENTS.md
View File

@ -182,3 +182,11 @@ KDE integration is part of this repository under `kde/`. Build and install it th
9. **The 9P namespace is the API.** Every capability is a file. Read, Write, or Rdwr. BlockOnce and Stream are special cases of Read. That's the entire interface.
10. **`Rdwr` is an atomic operation** — not a variant of read or write. It's write-then-read as one unit. Sub-agents, session creation, tool execution, and generation all use this primitive.
11. **Persisted state can contain garbage.** When debugging impossible errors, check if the data itself is corrupted. A failed command's stderr captured and stored as state will return that error on every subsequent read — the bug isn't in the code, it's in the data.
12. **Environment variables don't always propagate.** Tools run through toolsrv, which sets specific env vars. If a tool calls another binary that expects `$USER` or `$OLLIE_UNAME`, verify those are actually set in the execution context. Provide explicit fallbacks.
13. **Go build cache is aggressive.** When source changes don't appear in the binary, the cache may be stale. Use `go clean -cache` or verify with `go version -m <binary>` to check the embedded module version. Touch files if needed.
14. **Separate index files for separate concerns.** Don't cram session and agent data into one line. `session/idx` lists sessions; `session/{s}/agent/idx` lists agents per session. Simpler parsing, fewer race conditions, cleaner code.