chore(sync): merge upstream/main (42 commits) into our main

Adopts upstream's full LLM client refactor (PR plastic-labs#459: src/utils/clients.py
deleted in favor of the new src/llm/ package with per-backend handlers,
ConfiguredModelSettings, and ModelTransport). Conflict resolutions were
taken upstream-side via -X theirs and our customizations are re-applied
adjacent to the new structure rather than as parallel forks.

Notable upstream changes pulled in:
- LLM client refactor: src/llm/{api,backend,executor,runtime,tool_loop,...}
  with src/llm/backends/{anthropic,gemini,openai}.py
- ConfiguredModelSettings + ModelConfig replace per-component model fields
- New honcho-cli package, Zo Computer / Paperclip / SillyTavern / opencode
  integration docs
- Surprisal filter format fix (plastic-labs#581) — converged with our 4e7f136
- Many smaller fixes: dreamer thresholds, deriver blank-observation guard,
  vector sync retry budget, embed() string-input fix, etc.

Adjacent re-applications (deployment-critical):
- src/config.py: re-add LLM.CF_GATEWAY_AUTH_TOKEN
- src/llm/registry.py: inject cf-aig-authorization header in
  get_*_override_client factories when base_url targets a CF gateway
- src/embedding_client.py: same header injection on openai/gemini branches

Dropped (now redundant or replaceable):
- Per-specialist DEDUCTION_PROVIDER / INDUCTION_PROVIDER /
  *_THINKING_BUDGET_TOKENS overrides — covered by upstream's
  DREAM_DEDUCTION_MODEL_CONFIG__TRANSPORT etc. env vars
- get_provider() / get_thinking_budget() methods on BaseSpecialist —
  superseded by ConfiguredModelSettings on each specialist's MODEL_CONFIG
- src/utils/types.SupportedProviders — replaced by ModelTransport
- Custom Traefik service block in docker-compose.yml.example — Traefik
  configs remain in docker/traefik/ for users who want to wire it up
- Our 4e7f136 surprisal fix — identical to upstream's plastic-labs#581

Deployment notes for re-keying .env:
- LLM_CF_GATEWAY_API_KEY / LLM_CF_GATEWAY_BASE_URL / LLM_OPENAI_BASE_URL /
  LLM_OPENAI_COMPATIBLE_* / LLM_VLLM_* are no-ops now (extra='ignore'). Use
  per-component MODEL_CONFIG__BASE_URL / MODEL_CONFIG__API_KEY env vars
  (e.g. DREAM_DEDUCTION_MODEL_CONFIG__BASE_URL=...).
- LLM_CF_GATEWAY_AUTH_TOKEN remains as the single global needed for the
  cf-aig-authorization header.

Verification: ruff check src/ ✓, basedpyright src/ ✓ (0 errors).

Author: offendingcommit

.claude/skills/honcho-cli/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: honcho-cli
+description: Inspect and debug Honcho workspaces via the `honcho` CLI. Use when investigating peer representations, memory state, session context, queue status, or dialectic quality — any task that requires introspection of a Honcho deployment.
+allowed-tools: Bash(honcho:*), Bash(jq:*), Read, Grep
+---
+
+# Honcho CLI
+
+`honcho` wraps the Honcho Python SDK with agent-friendly defaults: JSON output, structured errors, input validation. Use it to inspect workspace state, debug peer memory, and diagnose the dialectic.
+
+## Output & config
+
+- **TTY**: human-readable tables (default when interactive)
+- **Piped / `--json`**: JSON — collection commands emit arrays, single-resource commands emit objects
+- **Exit codes**: `0` success · `1` client error (bad input, not found) · `2` server error · `3` auth error
+- **Config**: `~/.honcho/config.json` (shared with other Honcho tools). The CLI owns `apiKey` and `environmentUrl` at the top level; run `honcho init` to confirm or set them. Per-command scope (workspace / peer / session) is via `-w` / `-p` / `-s` flags or `HONCHO_*` env vars.
+
+## Command groups
+
+- `honcho config` — CLI configuration
+- `honcho workspace` — inspect, delete, search
+- `honcho peer` — inspect, card, chat, search
+- `honcho session` — inspect, messages, context, summaries
+- `honcho message` — list and get
+- `honcho conclusion` — list, search, create, delete
+
+## Rules
+
+- Always pass `--json` when processing output programmatically.
+- Run `honcho peer inspect` before `honcho peer chat` to understand context.
+- Use `honcho session context` to see exactly what an agent receives.
+- Never run `honcho workspace delete` without `honcho workspace inspect` first.
+- Check queue status when derivation seems stalled.
+- Compare peer card with conclusions to understand memory state.
+
+## Inspection tour
+
+When orienting to a Honcho deployment, walk outside-in:
+
+### 1. Understand the workspace
+
+```bash
+honcho workspace inspect --json
+```
+
+### 2. Find the peer
+
+```bash
+honcho peer list --json
+honcho peer inspect <peer_id> --json
+```
+
+### 3. Check peer's memory
+
+```bash
+honcho peer card <peer_id> --json
+honcho conclusion list --observer <peer_id> --json
+honcho conclusion search "topic" --observer <peer_id> --json
+```
+
+### 4. Debug a session
+
+```bash
+honcho session inspect <session_id> --json
+honcho message list <session_id> --last 20 --json
+honcho session context <session_id> --json
+honcho session summaries <session_id> --json
+```
+
+### 5. Search across workspace
+
+```bash
+honcho workspace search "query" --json
+honcho peer search <peer_id> "query" --json
+```
+
+## Debugging playbook
+
+### Peer not learning?
+
+```bash
+# Is observation enabled?
+honcho peer inspect <peer_id> --json | jq '.configuration'
+
+# Is the deriver queue processing messages?
+honcho workspace queue-status --json
+
+# What conclusions exist?
+honcho conclusion list --observer <peer_id> --json
+honcho conclusion search "expected topic" --observer <peer_id> --json
+```
+
+### Session context looks wrong?
+
+```bash
+# Raw context an agent would receive
+honcho session context <session_id> --json
+
+# Summaries feeding the context
+honcho session summaries <session_id> --json
+
+# Recent message history
+honcho message list <session_id> --last 50 --json
+```
+
+### Dialectic giving bad answers?
+
+```bash
+# What the peer card says
+honcho peer card <peer_id> --json
+
+# Conclusions on the specific topic
+honcho conclusion search "topic" --observer <peer_id> --json
+
+# Exercise the dialectic directly
+honcho peer chat <peer_id> "what do you know about X?" --json
+```

.claude/skills/honcho-integration/SKILL.md

@@ -91,6 +91,8 @@ Based on interview responses, implement the integration:
 
 ### Phase 4: Verification
 
+- If the Honcho CLI is available, run `honcho doctor` to confirm connectivity before testing the integration code
+- Use `honcho peer list` and `honcho peer chat` to verify peers exist and the dialectic endpoint works independently of the integration
 - Ensure all message exchanges are stored to Honcho
 - Verify AI peers have `observe_me=False` (unless user specifically wants AI observation)
 - Check that the workspace ID is consistent across the codebase
@@ -106,6 +108,16 @@ Based on interview responses, implement the integration:
 
 2. **Get an API key** ask the user to get a Honcho API key from <https://app.honcho.dev> and add it to the environment.
 
+3. **Verify with the CLI** (optional but recommended). If the user has the Honcho CLI installed (`pip install honcho-cli`), they can validate their setup before writing any integration code:
+
+   ```bash
+   honcho init          # persist API key + URL to ~/.honcho/config.json
+   honcho doctor        # verify connectivity, config, workspace health
+   honcho peer chat     # test the dialectic endpoint interactively
+   ```
+
+   This is the fastest way to confirm the API key and URL are correct before debugging SDK code.
+
 ## Installation
 
 ### Python (use uv)
@@ -524,6 +536,8 @@ When integrating Honcho into an existing codebase:
   - [ ] Pre-fetch pattern for simpler integrations
   - [ ] context() for conversation history
 - [ ] Store messages after each exchange to build user models
+- [ ] (Optional) Run `honcho doctor` to verify connectivity before testing integration code
+- [ ] (Optional) Use `honcho peer chat` to test dialectic queries independently
 
 ## Common Mistakes to Avoid