[folathecoder]

Summary

Builds aldwin.core: the Agentling agent and session factory, progressive skill loading and validation from ~/.aldwin/skills/, the per-call context manager that rebuilds the system message and trims history to 20 user exchanges, and OpenAI key checking, model discovery, and 3-attempt exponential-backoff retries. Wires aldwin.core into AldwinHost and adds StatusEvent to aldwin.protocol so retry notices reach the door without polluting streamed assistant text.

Ticket

• Closes ENG-380
• Dev plan: ENG-388
• Test plan: ENG-390

Changes

• Core agent and skills (src/aldwin/core/agent.py, src/aldwin/core/assets/instructions.md):
  • Added load_base_instructions(), load_skills(), build_agent(), new_session(), restore_session(), rebuild_agent(), and switch_session_model().
  • Validated SKILL.md frontmatter, enforced first-wins on duplicate skill names, rejected tools: entry points and reserved tool names in 0.0.1, and recorded InvalidSkill items for /skills.
• Context manager (src/aldwin/core/context.py):
  • Added build_context(home, limits), read_persona_stub(home, cap), and memory_block_stub(home, limits).
  • Rebuilt messages[0] on every model call (instructions + ## Persona capped at 2,000 chars + <memory> block) and trimmed history to the last 20 user turns while keeping assistant tool calls and their tool result messages together.
• OpenAI models, key check, and retries (src/aldwin/core/models.py):
  • Added check_key() (ok, invalid, no_access, network_error with 10 s timeout), list_chat_models() (chat-capable filter, sorted newest first), classify_model_error(), RetryingModel (3 retries with 1s, 2s, 4s +- 20% jitter, on_retry callback, no retry on auth errors or after mid-stream chunks), and build_openai_model().
• Host and protocol integration (src/aldwin/protocol/messages.py, src/aldwin/host/runner.py, docs/protocol.md):
  • Added non-terminal StatusEvent(kind="status", message=...) to aldwin.protocol.
  • Connected AldwinHost to build_agent, new_session, restore_session, switch_session_model, classify_model_error, and RetryingModel.on_retry.
• Tests (tests/test_context.py, tests/test_models.py, tests/test_agent.py, tests/integration/test_core_host.py, tests/live/test_openai_live.py, tests/test_architecture.py):
  • Added unit, integration, architecture boundary, and opt-in -m live test suites covering TC-01 through TC-20.

How it was tested

• Automated:
  • uv run pytest --cov=aldwin --cov-report=term-missing: 118 passed, 1 deselected in 0.63s (94% total coverage; core/agent.py 98%, core/context.py 92%, core/models.py 90%).
  • uv run ruff check src tests and uv run ruff format --check src tests: passed.
  • uv run mypy src tests and uv run mypy --strict src/aldwin/core src/aldwin/protocol: passed (0 issues across 36 files).
• Manual:
  • Opt-in live OpenAI test (TC-12) can be run with OPENAI_API_KEY=<key> uv run pytest -m live -v.

Notes for reviewers

• read_persona_stub and memory_block_stub in src/aldwin/core/context.py provide the seams that ENG-381 (core/persona.py and core/memory.py) will plug into.
• build_agent accepts tools: Sequence[Tool] (defaulting to ()) ready for ENG-381 and ENG-382 (builtin_tools).