Clawdie AI 8010ab3b3c docs: document hostd API proxy architecture for jail agents

The hostd-bridge now routes through the controlplane API instead of
direct Unix socket. 6 files updated:

- ARCHITECTURE.md: jail isolation section — hostd via API, no socket mount
- doc/CONTROLPLANE-ARCHITECTURE.md: hostd tree shows API proxy route
- doc/CONTROLPLANE-MESSAGE-CONTRACT.md: add POST /api/controlplane/hostd
  endpoint with request/response examples
- docs/public/operate/security.md: hostd section describes HTTP proxy
  model with CONTROLPLANE_SHARED_SECRET auth
- .env.example: document CONTROLPLANE_HOST_IP (default 10.0.1.1)
- doc/HANDOFF-ISO-AGENT.md: add sections 4 (hostd API proxy) and 5
  (legacy agent ID removal) to breaking changes

Build: pass | Tests: not run (Linux) (Sam & Claude)

2026-04-19 08:32:29 +02:00

4.1 KiB

Raw Blame History

Handoff: FreeBSD → ISO/Linux Agent

Date: 2026-04-18 Commits: dba0b69..7a0d388 (3 commits on main) Branch: main, pushed to codeberg.org:Clawdie/Clawdie-AI.git

Breaking changes to propagate

1. Skill system unified on library.yaml (`dba0b69`)

What changed:

--skill <path> flag removed from all pi subprocess invocations
Replaced with --no-skills everywhere (disables pi's built-in skill discovery)
Skills now loaded via --append-system-prompt from agent/library.yaml
Full skill content served on-demand through skills_search extension tool
loadSkillsCatalog() no longer accepts args — reads only from library.yaml
skillsDir removed from ControlplaneHeartbeatConfig, JailPiOptions, runner configs
Dead exports removed: PI_TUI_PROFILE_LABEL, PI_TUI_SKILLS_PATH, countSkillsInDir()
Net -214 lines

Files changed:

src/controlplane-runner.ts — --no-skills instead of --skill
src/jail-exec-runner.ts — skillsDir removed from interface + args
src/controlplane-heartbeat.ts — skillsDir dropped from config
src/controlplane-telegram.ts — loadSkillsCatalog() called without args
src/agent-runner.ts — SKILL_AWARE_PROFILES logic deleted, unconditional --no-skills
src/config.ts — dead exports removed
src/index.ts — skillsDir removed from heartbeat config
src/skills-discovery.ts — simplified to library.yaml only
src/controlplane-db.ts — countSkillsInDir() deleted

Test impact: 7 test files updated. All 1530 tests pass on FreeBSD.

2. PostgreSQL 17 → 18 references (`7a0d388`)

What changed:

All data17 paths → data (PG 18 uses /var/db/postgres/data)
All postgresql17-* package refs → postgresql18-*
18 files across setup scripts, skills, tests, docs, archived playbooks

Files the ISO build cares about:

setup.sh, setup/environment.ts — package names
src/hostd/privileged-commands.ts — example package name in comment
src/jail-schema.test.ts, src/hostd/privileged-commands.test.ts — test fixtures
docs/internal/scripts/setup-db-jail.sh — PGDATA path + packages
docs/internal/scripts/setup-controlplane-jail.sh — client package

3. run-*.sh removed from git (bb821e0+)

run-clawdie.sh and run-mevy.sh symlink deleted from git
run-*.sh added to .gitignore — generated by setup/service.ts at install time
rc.d service uses run-${AGENT_NAME}.sh written by generateRunScript()
ISO should run just setup-service which generates the correct script

4. hostd routed through controlplane API (`cac8b4a`)

Jail agents no longer connect to hostd Unix socket directly
hostd-bridge.ts rewritten as HTTP client → POST /api/controlplane/hostd
API authenticates via CONTROLPLANE_SHARED_SECRET, proxies to hostd daemon
No socket mount needed in jails — only network access to host IP
New config var: CONTROLPLANE_HOST_IP (default 10.0.1.1) — IP jails use to reach the API
Jail env CONTROLPLANE_API_URL now uses http://${CONTROLPLANE_HOST_IP}:${CONTROLPLANE_API_PORT} instead of localhost

5. Legacy agent IDs removed (`0f7fbc4`)

8 agents → 5 agents (removed sysadmin, db-admin, git-admin alias rows)
resolveCanonicalAgentId() removed — identity function since legacy IDs gone
CANONICAL_AGENT_MAP deleted, AGENT_JAIL_MAP trimmed to canonical IDs only
Role constraint in schema updated (removed legacy role values)

What still works unchanged

.pi/extensions/clawdie-harness/skill-tools.ts — self-contained, reads /opt/skills in jails
agent/library.yaml — source of truth, no changes needed
infra/jails.yaml — still mounts skills to /opt/skills:ro via nullfs
All extension tools — no breaking changes

Pending (not blocking ISO)

Pi CLI upgrade 0.58→0.67 has breaking API changes (session_start, getApiKeyAndHeaders, sourceInfo, promptSnippet) — not yet applied
Phase 7 jail isolation validation checklist not yet verified on deploy
Forgejo DB connection in git jail needs sslmode=disable or cert config — empty DB, errors intermittent

4.1 KiB Raw Blame History