Sam & Claude
a5139b5f7f
Real tailnet IPs and Telegram bot handles were being committed in docs/
memories/skills. Scrubbed all tracked markdown to ${VAR} placeholders; real
values now live in fleet.env (gitignored) and stay live via 'tailscale status'.
- add fleet.env.example (committed) + fleet.env (gitignored); .gitignore *.env
- AGENTS.md + HOST-MATRIX: masking convention so it can't recur
- also: domedog registered as Colibri agent (image-render/ffmpeg/build lane);
correct CAPABILITY-ROUTING example to real registered caps (domedog headless)
Past commits not rewritten (history moves to Codeberg at v1.0); this fixes HEAD.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
89 lines
5 KiB
Markdown
89 lines
5 KiB
Markdown
# Layered Soul Agent Rules
|
|
|
|
- Do not commit secrets, API keys, auth tokens, browser profiles, or raw credential files.
|
|
- Do not import raw sessions into another harness by default.
|
|
- Curate memories before adding them under `memories/curated/`.
|
|
- Keep Hermes-native runtime configuration in `hermes-soul`; this repository is the cross-harness contract.
|
|
- Public examples may reference private source repositories by URL/name, but must not quote or copy their private contents.
|
|
- Use `scripts/layered_soul.py validate .` before committing structural changes.
|
|
- Pull before editing hot shared files (`AGENTS.md`, `docs/HOST-MATRIX.md`, `docs/CAPABILITY-ROUTING.md`); keep history linear and re-check after rebases.
|
|
- When adapting for Colibri: reviewed skills map to `system_skills`, curated memory maps to `system_brain`, converted task manifests map to `system_ops`.
|
|
- When adapting for Hermes (upstream, Linux): load as profile context (SOUL.md + USER.md + IDENTITY.md). Hermes-native config and cron stay in `hermes-soul`.
|
|
- When adapting for hermes-osa (FreeBSD-native Hermes, clean-room MIT via `hermes-bsd`): same profile-context load; FreeBSD-specific gaps (voice, clipboard) are known and tracked in `docs/CLAWDIE-HERMES-FREEBSD-INTEGRATION.md`.
|
|
- When adapting for Pi/Codex/Claude Code/Zot: render the prompt bundle (`render-prompt`) and inject as task-scoped context. Durable findings flow back through reviewed commits.
|
|
|
|
## Quota exhaustion policy (cross-harness)
|
|
|
|
When any agent hits an API quota limit (429 / rate-limit):
|
|
|
|
1. **Calculate reset time** with `scripts/quota_reset_eta.py` — parses provider error
|
|
messages and converts to UTC/CEST correctly. Handles Beijing time (Z.AI/DeepSeek),
|
|
UTC (OpenRouter), and PDT (Anthropic/OpenAI).
|
|
|
|
2. **Check if task already resolved** with `scripts/task_dedup_before_retry.py` —
|
|
queries Colibri task board, checks git activity since block time. Skips retry
|
|
if another agent or operator already completed the work.
|
|
|
|
3. **Schedule retry** — create a one-shot cron at reset time + 60s buffer.
|
|
Never retry immediately (429 means quota, not transient).
|
|
|
|
4. **Report** — log to glasspane: provider, reset time, task status, action taken.
|
|
|
|
Rule: **never retry a quota-blocked task without checking whether it was
|
|
already solved.** Tokens are money. A solved task retried is waste.
|
|
|
|
## Active infrastructure
|
|
|
|
- Forgejo: code.smilepowered.org (SSH port 2222)
|
|
- Vaultwarden: vault.smilepowered.org (SSL)
|
|
- Tailscale: debby=${DEBBY_TS_IP}, domedog=${DOMEDOG_TS_IP}, osa=${OSA_TS_IP}
|
|
- Commit identity: `hello@clawdie.si` for all project commits
|
|
|
|
### Topology & channel masking (do not commit real values)
|
|
|
|
Real Tailscale IPs and Telegram bot handles **never go into committed files** — they
|
|
were leaked once; not again. Committed docs reference variable names only
|
|
(`${OSA_TS_IP}`, `${HERMES_BOT}`, …). To resolve them:
|
|
|
|
- **IPs** are live-discoverable any time with `tailscale status`.
|
|
- **Handles + IPs** are stored in `fleet.env` (gitignored). Copy `fleet.env.example` →
|
|
`fleet.env` and fill from `tailscale status` / Vaultwarden, then `source fleet.env`.
|
|
|
|
When editing docs: if you're about to paste a `100.x` IP or an `@…_bot` handle, stop and
|
|
use the placeholder instead.
|
|
|
|
## Agent matrix (5 agents across 3 hosts, 2 OS families)
|
|
|
|
| Agent | Host | Harness | OS | Isolation | Role |
|
|
| ---------- | ------- | ----------------------- | ---------- | ------------------ | ------------------------- |
|
|
| Hermes | debby | Hermes Agent (upstream) | Debian 13 | Docker | Orchestrator, soul backup |
|
|
| Zot | debby | Zot RPC | Debian 13 | Docker | Coding, media workflows |
|
|
| Claude | domedog | Claude Code | Linux | Docker | Verification, review |
|
|
| Codex | osa | Codex CLI | FreeBSD 15 | Bastille jail | ISO builds, validation |
|
|
| hermes-osa | osa | Hermes Agent (FreeBSD) | FreeBSD 15 | host service first | Native FreeBSD Hermes |
|
|
|
|
**Survivability**: Linux/Docker and FreeBSD/jails are complementary safeguards.
|
|
A vulnerability that kills one platform cannot kill the other. Agents can be
|
|
relocated across platforms in minutes via layered-soul identity injection.
|
|
|
|
## Private sources
|
|
|
|
- `hermes-soul`: git@code.smilepowered.org:clawdie/hermes-soul.git (private, operator access only)
|
|
- `hermes-bsd`: git@code.smilepowered.org:clawdie/hermes-bsd.git (public, MIT-licensed FreeBSD patches)
|
|
- `clawdie-ai`: git@code.smilepowered.org:clawdie/clawdie-ai.git (private)
|
|
- `clawdie-iso`: git@code.smilepowered.org:clawdie/clawdie-iso.git (private)
|
|
|
|
## Quick reference
|
|
|
|
```sh
|
|
# Validate
|
|
python3 scripts/layered_soul.py validate .
|
|
|
|
# See what's available from hermes-soul
|
|
python3 scripts/layered_soul.py plan-private-source \
|
|
examples/private-sources/hermes-soul.example.json \
|
|
--source-root ~/hermes-soul
|
|
|
|
# Render for a harness
|
|
python3 scripts/layered_soul.py render-prompt . --output /tmp/soul-prompt.md
|
|
```
|