[LinuxDevil]

What

• LOU-W4: agent.session({ id?, store? }) returns an AgentSession (id, send(input, { signal }), messages, load(), clear()). SessionStore interface with MemorySessionStore (default) and FileSessionStore(dir) (one JSON file per session, temp file + rename, id must match ^[A-Za-z0-9_-]{1,128}$).
• LOU-W7: loadProjectInstructions({ cwd?, files?, stopAt?, maxChars? }) (exported from the root) and opt-in createAgent({ projectInstructions: true | { cwd, files } }), appended under ## Project instructions (from AGENTS.md).
• Docs: new docs/sessions.md, "Project instructions" section in docs/configuration.md, README bullets + session snippet, regenerated llms.txt/llms-full.txt.

Why

send() was single-turn, and nothing gave users multi-turn memory or the repo's own AGENTS.md. Both are opt-in additions.

How

• Sessions are a thin layer: the session owns the transcript and passes [...history, user] as the existing input: Message[] of AgentExecutor.execute, then stores result.messages minus the system message. No executor change; no checkpoint/resume use (LOU-U8 untouched).
• Sends are serialized with a promise queue. A throwing or aborted send leaves the transcript unchanged; saved transcripts are trimmed to a provider-valid prefix (no assistant tool-call turn without all its results).
• createAgent.ts edits are additive: the executor call is pulled into a local run helper that send and sessions share.

How verified

Run on the result of merging origin/main at b5cd5f5 (LOU-X6):

• npx tsc --noEmit: clean
• npm run lint: 0 errors (433 warnings, none in new files)
• build + create-loushy-agent build: success
• npm run test:coverage: Test Files 115 passed; Tests 1625 passed, 4 skipped
• npm run fallow: exit 0
• npm run test:types: no errors
• npm run docs:verify-snippets: all 56 snippets type-check against src/; 6 also run cleanly
• npm run docs:llms:check: exit 0

Notes for reviewer

• The class is named AgentSession because Session is already exported from src/data/models.ts.
• agent.stream does not exist on main yet, so session.stream() is not added; add it when agent.stream lands.
• loadProjectInstructions is synchronous (it runs once inside the sync createAgent). Empty/whitespace-only files are skipped.
• session.messages is empty for a resumed session until load() or the first send() completes.

🤖 Generated with Claude Code