diff --git a/memory/2026-03-12.md b/memory/2026-03-12.md index 838351b..fc68e1b 100644 --- a/memory/2026-03-12.md +++ b/memory/2026-03-12.md @@ -52,3 +52,4 @@ - 21:53 UTC heartbeat: SOR clean (no working tree changes). Latest commit remains `da6899b` (ArchSpirit Battlefield target candidates fix). No blockers; priorities unchanged. - 22:23 UTC heartbeat: SOR status: clean | latest: da6899b Fix: include ArchSpirit in Battlefield ability target candidates - 22:53 UTC heartbeat: SOR clean (`git status --short` empty). Latest commit remains `da6899b` (ArchSpirit target candidate fix). No blockers or priority changes. +- 23:57 UTC heartbeat: SOR repo clean (no working tree changes). HEAD still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers or priority changes. diff --git a/memory/2026-03-13.md b/memory/2026-03-13.md new file mode 100644 index 0000000..490d8b5 --- /dev/null +++ b/memory/2026-03-13.md @@ -0,0 +1,50 @@ +- 00:31 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; no priority change. +- 00:34 UTC heartbeat: SOR clean (`git status --short` empty). Latest commit remains `da6899b` (ArchSpirit battlefield target candidate fix). No blockers; priorities unchanged. +- 00:38 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit remains `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers detected; priorities unchanged. +- 01:08 UTC heartbeat: SOR status check. + - git status --short: clean + - git log -1 --oneline: da6899b Fix: include ArchSpirit in Battlefield ability target candidates + - blockers: none detected +- 01:28 UTC heartbeat: SOR clean (`git status --short` empty). Latest commit remains `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers or priority changes. +- 01:58 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit `da6899b` (ArchSpirit target candidate fix). No blockers or priority changes. +- 02:26 UTC heartbeat: SOR check complete. Latest commit: da6899b Fix: include ArchSpirit in Battlefield ability target candidates. Status: clean. +- 02:56 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (ArchSpirit targeting fix). No blockers; no priority changes. +- 03:26 UTC heartbeat: SOR status check complete. status= + clean + last_commit=da6899b Fix: include ArchSpirit in Battlefield ability target candidates + blockers=none observed. +- 03:56 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit `da6899b` (ArchSpirit target candidate fix). No blockers; priorities unchanged. +- 03:57 UTC heartbeat: SOR repo clean (no working tree changes). HEAD still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers or priority changes. +- 04:27 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 04:57 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 05:27 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 05:57 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 06:27 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 06:57 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 07:27 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 07:57 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 07:57 UTC heartbeat: Checked `/SOR` status. Repo clean (`git status --short` empty). HEAD `da6899b` — "Fix: include ArchSpirit in Battlefield ability target candidates." No blockers observed; next action is to continue with queued SOR priorities when requested. +- 08:27 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 08:57 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit remains `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 09:27 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit remains `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 09:57 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 10:27 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 10:57 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 11:27 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 11:50 UTC: Recovered Prime Nextcloud Talk setup details. Verified room token gnrm73b4. Nextcloud Talk bot rename required uninstall+reinstall; migrated room bot from "OpenClaw Prime" to "Prime" (new bot id 3) using existing webhook+secret from cred-nextcloud-prime. Added runbook shard-memory/runbooks/prime-nextcloud-setup.md. +- 11:57 UTC heartbeat: Checked `/SOR`. Working tree clean (`git status --short` empty). HEAD still `da6899b` (ArchSpirit battlefield target candidate fix). No blockers or priority changes. +- 12:27 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 12:57 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 13:11 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit remains `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 13:25 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 13:36 UTC: Drafted bridge architecture docs for chattr transport model (bridge-spec-v1.md, bridge-sequence.md, bridge-k8s-v1.yaml) under shard-memory/runbooks. Decisions captured: canonical conversation IDs, handoff packet continuity, unmentioned fanout to both shard+prime, session-aware adapter-first integration. +- 13:55 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit remains `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 14:25 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit remains `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 14:55 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit remains `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 15:25 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit remains `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 13:58 UTC: Created Gitea repo ashard_bot/chattr-bridge, added collaborators dingo + prime, scaffolded M0 bridge code (FastAPI skeleton, health/metrics, adapter callback stub, poller stub), committed and pushed main. +- 15:57 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 15:57 UTC heartbeat: Re-checked `/SOR`; repo remains clean and unchanged. HEAD `da6899b` (ArchSpirit battlefield targeting fix). No blockers, decisions, or priority changes. +- 16:27 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit still `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 16:57 UTC heartbeat: SOR repo clean (`git status --short` empty). Latest commit remains `da6899b` (Fix: include ArchSpirit in Battlefield ability target candidates). No blockers; priorities unchanged. +- 17:35 UTC heartbeat: SOR unchanged/clean (latest da6899b). Active signal: chattr-bridge validation in shard hit relay-loop behavior (bridge re-ingesting callback-posted messages). Mitigation committed (`BRIDGE_IGNORE_SENDERS`); staged shard/prime/fanout matrix pending rerun after deploy/env update. diff --git a/runbooks/bridge-impl-plan.md b/runbooks/bridge-impl-plan.md new file mode 100644 index 0000000..f4dcdc3 --- /dev/null +++ b/runbooks/bridge-impl-plan.md @@ -0,0 +1,175 @@ +# Bridge Implementation Plan (MVP) + +## Goal +Implement bridge v1.1 to relay messages between `agentchattr` and authoritative runtimes (`shard`, `prime`) with handoff continuity, dedupe, and loop controls. + +## Scope (MVP) +- Poll/read messages from chattr +- Route envelopes to shard/prime adapters +- Receive adapter responses and post back to chattr +- Maintain conversation_id + mapping state +- Enforce dedupe + loop controls +- Basic observability + retries + DLQ + +## Out of Scope (post-MVP) +- Full event-driven webhooks replacing poll +- Advanced semantic fork classifier +- Multi-region HA / horizontal shard orchestration + +--- + +## Milestones + +### M0 — Repo + service skeleton +- Create `chattr-bridge` repo/folder +- Language/runtime choice (Python FastAPI recommended for speed) +- Config loader (env + file) +- Health endpoints: `/healthz`, `/readyz`, `/metrics` +- Structured logging with correlation IDs + +Deliverable: +- Service boots in dev with no routing enabled + +### M1 — State layer +- sqlite init + migrations +- Tables from spec v1.1: + - conversations + - surface_bindings + - message_map + - handoff_state + - relay_events + - retry_queue + - dead_letter +- Data access layer + transaction helpers + +Deliverable: +- CRUD tests pass for all core state ops + +### M2 — Chattr client +- Poll loop (`BRIDGE_POLL_INTERVAL_MS`) +- Read channel messages with cursor +- Normalize into canonical envelope +- Post message API back into channel/thread + +Deliverable: +- Echo test path (bridge reads and re-posts tagged test message) + +### M3 — Routing engine +- Mention detection +- Unmentioned fanout to both targets +- conversation_id start/reuse/fork logic +- dedupe key generation + lookup +- loop controls (hop/cycle/cooldown/self-echo) + +Deliverable: +- Deterministic routing tests (table-driven) + +### M4 — Adapter integration +- HTTP adapter client for `/ingest` +- Ack/error handling per schema +- Retry backoff + DLQ integration +- Callback endpoint `/adapter/events` for async responses + +Deliverable: +- Simulated adapter integration test suite green + +### M5 — Handoff continuity +- Build handoff packets on first route/surface switch +- Drift trigger checks (idle/messages/manual) +- Payload caps + truncation policy + +Deliverable: +- Surface-switch continuity tests pass + +### M6 — k8s deployment +- Build/push image +- Apply `bridge-k8s-v1.yaml` (with real image + secrets) +- Wire network reachability to prime adapter +- Smoke tests in shard namespace + +Deliverable: +- Running bridge pod with successful end-to-end relay + +### M7 — tuning pass +- Fanout response etiquette tuning under real usage +- Conversation fork heuristic conservative defaults +- Poll interval + timeout tuning + +Deliverable: +- Ops baseline doc + tuned defaults + +--- + +## Suggested implementation layout + +```text +chattr-bridge/ + app/ + main.py + config.py + logging.py + metrics.py + api/ + health.py + adapter_events.py + core/ + envelope.py + routing.py + handoff.py + dedupe.py + loop_guard.py + conversation.py + clients/ + chattr_client.py + adapter_client.py + store/ + db.py + migrations/ + models.py + repo.py + workers/ + poller.py + retry_worker.py + tests/ + unit/ + integration/ + Dockerfile + pyproject.toml + README.md +``` + +--- + +## Integration order recommendation +1. Shard adapter first (local/easier control) +2. Prime adapter second (validate network/auth path) +3. Enable fanout after both stable + +--- + +## Operational checklist +- [ ] Secrets injected (signing key, chattr token) +- [ ] DB PVC mounted + writable +- [ ] Prime adapter reachable from bridge pod +- [ ] TLS/auth validated if adapter external +- [ ] Retry/DLQ dashboards visible +- [ ] Alert on adapter error rate and queue depth + +--- + +## Risk watchlist +- Poll jitter causing duplicate reads -> mitigate with robust dedupe +- Fanout noise causing duplicate-value responses -> runtime etiquette + post-hoc tuning +- Over-eager forking -> keep fork heuristic conservative; prefer reuse unless explicit fork +- Prime adapter reachability -> solve early before broad rollout + +--- + +## MVP completion definition +MVP is complete when: +- dingo -> chattr unmentioned message reaches both adapters +- valid 0/1/2 responses handled cleanly +- explicit mention routing works +- conversation_id continuity + handoff behavior verified +- no relay loops under stress test +- bridge survives restart without state loss diff --git a/runbooks/bridge-k8s-v1.yaml b/runbooks/bridge-k8s-v1.yaml new file mode 100644 index 0000000..9e18bac --- /dev/null +++ b/runbooks/bridge-k8s-v1.yaml @@ -0,0 +1,158 @@ +# Draft scaffold only (not production-ready app image) +# Purpose: establish k8s shape for bridge v1.1 deployment in namespace shard. + +apiVersion: v1 +kind: ConfigMap +metadata: + name: chattr-bridge-config + namespace: shard +data: + BRIDGE_ACTOR_IDS: "dingo,shard,prime" + BRIDGE_DEFAULT_CHANNEL: "general" + BRIDGE_UNMENTIONED_POLICY: "fanout_all" + BRIDGE_MAX_HOPS: "4" + BRIDGE_DEDUPE_TTL_SEC: "600" + BRIDGE_HANDOFF_INACTIVITY_MIN: "30" + BRIDGE_HANDOFF_MAX_MSGS: "40" + BRIDGE_HANDOFF_MAX_PAYLOAD_KB: "16" + BRIDGE_RELAY_COOLDOWN_SEC: "5" + BRIDGE_ADAPTER_TIMEOUT_SEC: "45" + BRIDGE_POLL_INTERVAL_MS: "1000" + BRIDGE_LOG_LEVEL: "info" + BRIDGE_DB_PATH: "/var/lib/chattr-bridge/bridge.db" + SHARD_ADAPTER_URL: "http://shard-adapter.shard.svc.cluster.local:8081/ingest" + # PRIME_ADAPTER_URL may be internal service or external URL depending on Prime host reachability. + # If external, ensure network policy + auth + TLS are configured. + PRIME_ADAPTER_URL: "http://prime-adapter.shard.svc.cluster.local:8081/ingest" + CHATTR_BASE_URL: "https://chattr.aeternalisgames.com" + +--- +apiVersion: v1 +kind: Secret +metadata: + name: chattr-bridge-secrets + namespace: shard +type: Opaque +stringData: + BRIDGE_SHARED_SIGNING_KEY: "REPLACE_ME" + CHATTR_API_TOKEN: "REPLACE_ME" + +--- +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: chattr-bridge-state + namespace: shard +spec: + accessModes: ["ReadWriteOnce"] + resources: + requests: + storage: 2Gi + +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: chattr-bridge + namespace: shard + labels: + app: chattr-bridge +spec: + replicas: 1 + selector: + matchLabels: + app: chattr-bridge + template: + metadata: + labels: + app: chattr-bridge + spec: + securityContext: + runAsNonRoot: true + seccompProfile: + type: RuntimeDefault + containers: + - name: bridge + # Replace with actual built image once implementation exists + image: ghcr.io/aeternalisgames/chattr-bridge:v1.1-draft + imagePullPolicy: IfNotPresent + envFrom: + - configMapRef: + name: chattr-bridge-config + - secretRef: + name: chattr-bridge-secrets + ports: + - name: http + containerPort: 8080 + securityContext: + allowPrivilegeEscalation: false + readOnlyRootFilesystem: true + capabilities: + drop: ["ALL"] + volumeMounts: + - name: state + mountPath: /var/lib/chattr-bridge + readinessProbe: + httpGet: + path: /readyz + port: 8080 + initialDelaySeconds: 8 + periodSeconds: 10 + livenessProbe: + httpGet: + path: /healthz + port: 8080 + initialDelaySeconds: 20 + periodSeconds: 20 + resources: + requests: + cpu: 100m + memory: 128Mi + limits: + cpu: 1 + memory: 512Mi + volumes: + - name: state + persistentVolumeClaim: + claimName: chattr-bridge-state + +--- +apiVersion: v1 +kind: Service +metadata: + name: chattr-bridge + namespace: shard +spec: + selector: + app: chattr-bridge + ports: + - name: http + port: 8080 + targetPort: 8080 + +--- +# Optional ingress only if you need external callbacks into bridge. +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: chattr-bridge-ingress + namespace: shard + annotations: + cert-manager.io/cluster-issuer: letsencrypt-godaddy + nginx.ingress.kubernetes.io/ssl-redirect: "true" +spec: + ingressClassName: nginx + rules: + - host: bridge.aeternalisgames.com + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: chattr-bridge + port: + number: 8080 + tls: + - hosts: ["bridge.aeternalisgames.com"] + secretName: bridge-aeternalisgames-tls diff --git a/runbooks/bridge-scaffold-layout.md b/runbooks/bridge-scaffold-layout.md new file mode 100644 index 0000000..da2cc6f --- /dev/null +++ b/runbooks/bridge-scaffold-layout.md @@ -0,0 +1,73 @@ +# Bridge Code Scaffold (initial) + +## Stack recommendation +- Python 3.11+ +- FastAPI (API surface) +- httpx (adapter/chattr clients) +- sqlite + SQLAlchemy or sqlite3+repo pattern +- Prometheus client for `/metrics` + +## Initial files + +```text +chattr-bridge/ + app/ + main.py # app startup, wiring workers + config.py # env parsing and validation + logging.py # structured logger + correlation support + metrics.py # Prometheus counters/histograms + + api/ + health.py # /healthz /readyz + adapter_events.py # /adapter/events callback endpoint + + core/ + envelope.py # canonical schema + validators + routing.py # mention/fanout target selection + conversation.py # start/reuse/fork rules + handoff.py # handoff creation + truncation + dedupe.py # dedupe key + TTL checks + loop_guard.py # hop/cycle/cooldown/self-echo + + clients/ + chattr_client.py # read/post interactions + adapter_client.py # /ingest calls, ack/error parsing + + store/ + db.py # sqlite init/connection + migrations.py # schema management + repo.py # table operations + + workers/ + poller.py # inbound chattr polling loop + retry_worker.py # retry queue processor + + tests/ + unit/ + test_routing.py + test_conversation.py + test_dedupe.py + test_loop_guard.py + test_handoff.py + integration/ + test_adapter_contract.py + test_retry_queue.py + test_restart_resume.py + + Dockerfile + pyproject.toml + README.md +``` + +## Phase-0 TODOs +- Build config struct with sane defaults from v1.1 spec +- Implement minimal health endpoints +- Add no-op poll loop with logs only +- Add sqlite bootstrap and migrations +- Add first unit tests for routing + dedupe + +## CI minimum +- lint +- type check (optional initially) +- unit tests +- integration tests (mock adapters) diff --git a/runbooks/bridge-sequence.md b/runbooks/bridge-sequence.md new file mode 100644 index 0000000..7d64a57 --- /dev/null +++ b/runbooks/bridge-sequence.md @@ -0,0 +1,88 @@ +# Bridge Sequence Flows (v1.1) + +## Actors +- Dingo (human) +- agentchattr +- bridge +- shard-adapter -> Shard runtime +- prime-adapter -> Prime runtime + +--- + +## Conversation-ID behavior note +- Inherit existing `conversation_id` for mapped reply/thread/job by default. +- Create new `conversation_id` for new top-level conversation starts. +- Fork to new `conversation_id` only on explicit fork or policy-triggered drift split. + +--- + +## Flow A: Unmentioned message (fanout to both) + +1. Dingo posts in `#general`: "Status check" +2. bridge reads event from chattr +3. bridge resolves targets = `[shard, prime]` (fanout policy) +4. bridge assigns/reuses `conversation_id` +5. bridge builds envelope + handoff (if needed) +6. bridge sends `POST /ingest` to shard-adapter and prime-adapter +7. adapters inject into existing runtime sessions +8. runtimes may respond (0/1/2 responses are all valid) +9. adapters return response events with same `correlation_id` +10. bridge posts responses back to chattr channel/thread +11. bridge records audit + dedupe state + +--- + +## Flow B: Explicit mention to one actor + +1. Dingo posts: "@prime please review routing" +2. bridge parses explicit target = `prime` +3. bridge sends only to prime-adapter +4. Prime response posted back with attribution `prime` + +--- + +## Flow C: Cross-agent relay (prefer explicit mention) + +1. Prime response includes explicit `@shard` ask +2. bridge routes to shard-adapter (increment `hop_count`) +3. Shard responds +4. bridge posts response +5. if loop controls trigger (hop/cycle/cooldown), bridge halts relay and posts loop-guard notice + +Note: Agent-to-agent relay should generally require explicit mention to reduce noisy ping-pong. + +--- + +## Flow D: Surface switch handoff (Telegram -> chattr) + +1. Ongoing context exists on Telegram +2. First message for same logical task arrives on chattr +3. bridge attaches handoff packet: + - conversation_id + - task summary + - recent context window + - participants + - memory refs +4. adapter injects handoff + message into existing runtime +5. runtime answers with continuity preserved by handoff context + +--- + +## Flow E: Dedupe handling + +1. Duplicate delivery/event replay received by bridge +2. dedupe_key matches processed entry +3. bridge drops duplicate +4. optional debug log entry only; no reroute + +--- + +## Suggested defaults +- max_hop_count: 4 +- dedupe_ttl_sec: 600 +- handoff_inactivity_min: 30 +- handoff_max_msgs_without_refresh: 40 +- handoff_max_payload_kb: 16 +- adapter_timeout_sec: 45 +- retry_max_attempts: 8 +- relay_cooldown_sec: 5 diff --git a/runbooks/bridge-spec-v1.md b/runbooks/bridge-spec-v1.md new file mode 100644 index 0000000..ba8151f --- /dev/null +++ b/runbooks/bridge-spec-v1.md @@ -0,0 +1,278 @@ +# Bridge Spec v1.1 — Shard/Prime continuity over agentchattr + +## Status +Draft v1.1 (post Prime review) + +## Objective +Use `agentchattr` as shared surface + transport while keeping **Shard** and **Prime** as authoritative external runtimes. + +## Non-goals (v1) +- No replacement/clone brains inside chattr +- No full shared canonical cognition state yet +- No chattr-owned memory authority + +## Confirmed decisions +- Actor IDs: `dingo`, `shard`, `prime` +- Default channel: `general` +- Unmentioned messages: fanout to both `shard` and `prime` +- Runtime determines if/when to respond + +--- + +## Design principle +Bridge treats Shard/Prime as external authoritative actors. + +- chattr is not identity authority +- chattr is not memory authority +- chattr is not cognition scheduler +- chattr is UI + event stream + relay metadata + +--- + +## Memory authority (explicit) +Priority order for memory truth: +1. Agent runtime long-term memory stores (Shard/Prime memory files + approved stores) +2. Shared source-of-truth memory repo/sync target (e.g., Nextcloud/git mirror) +3. Handoff packets (ephemeral continuity aid) +4. chattr message history (transport/UI log only) + +Rule: bridge must not overwrite runtime memory directly except via normal runtime message ingestion pathways. + +--- + +## Conversation lifecycle rules + +### Start +Create new `conversation_id` when all are true: +- no explicit `reply_to` mapping to existing conversation +- no active recent binding in same channel/thread window +- no user command to attach to existing conversation + +### Reuse +Reuse existing `conversation_id` when any are true: +- message replies to mapped prior message +- message belongs to mapped surface thread/job +- explicit `/conv use ` directive + +### Fork +Fork into new `conversation_id` when any are true: +- explicit `/conv fork` +- topic switch heuristic crosses threshold (configurable) +- bridge policy marks branch due to drift conflict + +### Inheritance notes +- Thread/job-local messages inherit parent conversation by default. +- New top-level channel messages may reuse recent active conversation if within idle threshold. + +--- + +## Canonical envelope (internal) + +```json +{ + "version": 1, + "id": "uuid", + "ts": "2026-03-13T14:00:00Z", + "conversation_id": "conv-uuid", + "correlation_id": "corr-uuid", + "source": { + "surface": "agentchattr", + "channel": "general", + "thread_id": "optional", + "message_id": "chattr-msg-id", + "actor_id": "dingo" + }, + "targets": ["prime", "shard"], + "routing": { + "mention_explicit": false, + "fanout": true, + "hop_count": 0, + "reply_to_id": null + }, + "content": { + "text": "message body", + "display_text": "message body" + }, + "causality": { + "parent_message_id": null, + "origin_surface": "agentchattr", + "origin_message_id": "chattr-msg-id", + "trace": ["dingo->prime", "prime->shard"] + }, + "safety": { + "dedupe_key": "sha256(...)", + "ttl_sec": 600 + }, + "handoff": null +} +``` + +--- + +## Handoff packet (required v1) + +```json +{ + "handoff_version": 1, + "conversation_id": "conv-uuid", + "agent": "prime", + "source_surface": "telegram", + "target_surface": "agentchattr", + "source_thread": "telegram:chat/thread", + "task_summary": "Diagnosing bridge architecture", + "recent_context": ["..."], + "participants": ["dingo", "prime", "shard"], + "memory_refs": ["memory/2026-03-13.md"], + "origin_message_id": "telegram:1491", + "correlation_id": "corr-uuid" +} +``` + +### Handoff limits +- `task_summary`: max 1000 chars +- `recent_context`: max 20 items, each max 500 chars +- total handoff payload: max 16 KB +- if oversized: truncate oldest `recent_context` first, then summarize + +### Handoff triggers +- first route into a new surface binding +- inactivity > 30 min +- > 40 routed msgs since last handoff +- explicit `/handoff refresh` + +--- + +## Routing + fanout etiquette + +1. Explicit mention wins + - `@prime` => prime only + - `@shard` => shard only +2. No mention => fanout both targets +3. Fanout response etiquette + - 0 responses allowed (both decide no response) + - 1 response allowed (one defers) + - 2 responses allowed (both add value) +4. Agents should avoid duplicate-value replies; prefer defer if no net-new value +5. Agent-to-agent relays should generally require explicit mention (`@other`) + +--- + +## Loop prevention (beyond hop count) + +Required controls: +- max `hop_count` (default 4) +- self-echo suppression (actor cannot receive its own emitted content back) +- causality-cycle detection via trace ring buffer +- relay cooldown per `(conversation_id, actor_pair)` window (e.g. 5s) +- dedupe via `dedupe_key` TTL index + +--- + +## Session-aware adapter definition + +A session-aware adapter MUST: +1. Inject into existing runtime identity/session path (not spawn disposable clone by default) +2. Preserve metadata: source surface/channel/thread, actor, conversation_id, correlation_id +3. Return deterministic ack/error envelope +4. Emit responses with correlation back to bridge +5. Support idempotent re-delivery by `dedupe_key` + +--- + +## Adapter contract (HTTP v1.1) + +### POST /ingest response schema +```json +{ + "accepted": true, + "adapter_message_id": "adapter-msg-uuid", + "correlation_id": "corr-uuid", + "status": "queued", + "retryable": false, + "error": null +} +``` + +### Error schema +```json +{ + "accepted": false, + "correlation_id": "corr-uuid", + "status": "rejected", + "retryable": true, + "error": { + "code": "SESSION_BUSY", + "message": "target session temporarily unavailable", + "details": {} + } +} +``` + +### Callback event example +```json +{ + "type": "response", + "actor_id": "prime", + "conversation_id": "conv-uuid", + "correlation_id": "corr-uuid", + "content": { "text": "Prime response" } +} +``` + +--- + +## State schema (v1 explicit) + +Minimum sqlite tables: +- `conversations(id, created_at, updated_at, status, topic_hint)` +- `surface_bindings(surface, channel, thread_id, conversation_id, updated_at)` +- `message_map(surface, source_message_id, bridge_message_id, conversation_id, dedupe_key, created_at)` +- `handoff_state(conversation_id, actor_id, last_handoff_at, last_summary_hash, msg_count_since_handoff)` +- `relay_events(id, correlation_id, source_actor, target_actor, result, created_at)` +- `retry_queue(id, envelope_json, attempt_count, next_attempt_at, last_error)` +- `dead_letter(id, envelope_json, failure_reason, failed_at)` + +--- + +## Reliability and safety +- Exponential backoff retries: 1,2,4,8,... max 60s +- Max attempts: 8 then DLQ +- Signed auth bridge<->adapter (shared secret/JWT) +- No raw secrets in payloads/logs +- Audit log required for all relays + +--- + +## Observability +Metrics: +- `messages_in_total` +- `messages_routed_total{target}` +- `adapter_errors_total{target,code}` +- `handoff_bootstraps_total` +- `dedupe_drops_total` +- `loop_guard_drops_total` +- `relay_cooldown_drops_total` +- `end_to_end_latency_ms` + +Endpoints: +- `/healthz` +- `/readyz` +- `/metrics` + +--- + +## MVP acceptance criteria +1. Unmentioned `#general` message fans out to both targets. +2. Explicit mention routes only to named target. +3. Unmentioned fanout allows 0/1/2 valid responses. +4. First cross-surface route includes handoff packet. +5. conversation_id is reused correctly via reply/thread mapping. +6. fork rules create new conversation_id when explicitly requested. +7. Duplicate dedupe key is dropped. +8. Loop controls prevent runaway ping-pong. + +--- + +## Forward path +- v2: conversation registry with stronger ownership/surface mappings +- v3: canonical shared conversation graph/state outside transports diff --git a/runbooks/bridge-test-plan.md b/runbooks/bridge-test-plan.md new file mode 100644 index 0000000..c298904 --- /dev/null +++ b/runbooks/bridge-test-plan.md @@ -0,0 +1,94 @@ +# Bridge Test Plan (MVP) + +## Test levels +- Unit: routing, dedupe, loop guard, conversation rules +- Integration: chattr client + adapters + sqlite +- E2E: k8s deployment with real channel traffic + +--- + +## A. Unit tests + +### A1 Routing +- `@prime` routes to prime only +- `@shard` routes to shard only +- no mention routes to both + +### A2 Conversation rules +- reply/thread inherits conversation_id +- new top-level starts new conversation_id +- explicit fork creates new conversation_id + +### A3 Dedupe +- same dedupe_key processed once +- expired dedupe key accepted again after TTL + +### A4 Loop controls +- hop_count > max blocked +- self-echo blocked +- cycle trace detection blocks repeated ring +- relay cooldown blocks rapid ping-pong + +### A5 Handoff limits +- payload > max truncates correctly +- handoff trigger fires on inactivity/msg threshold + +--- + +## B. Integration tests + +### B1 Adapter ack/error +- accepted queued response handled +- retryable error enters retry queue +- non-retryable error goes directly to DLQ/log + +### B2 Retry worker +- exponential backoff schedule honored +- max attempts sends to DLQ + +### B3 Callback responses +- adapter callback with correlation_id maps to correct chattr thread + +### B4 Restart resilience +- restart service; cursors/state resume without duplicate flood + +--- + +## C. E2E scenarios (k8s) + +### C1 Fanout baseline +Input: unmentioned message in #general +Expected: both adapters receive ingest, 0/1/2 responses accepted + +### C2 Explicit mention +Input: @prime request +Expected: shard adapter not called + +### C3 Cross-agent relay +Input: Prime mentions @shard in response +Expected: one relay hop; loop guard active if repeated chain + +### C4 Surface switch handoff +Input: simulate Telegram-origin conversation routed into chattr +Expected: handoff packet present and conversation_id continuity maintained + +### C5 Failure path +Input: prime adapter unreachable +Expected: retries, then DLQ, no bridge crash + +--- + +## Acceptance gates +- 95%+ unit test pass (100% required in CI) +- all integration tests green +- E2E C1-C5 pass in shard namespace +- no unbounded queue growth under 30-min soak + +--- + +## Observability checks during E2E +- `messages_in_total` increments +- `messages_routed_total{target}` matches expected fanout +- `dedupe_drops_total` increases only in duplicate scenarios +- `loop_guard_drops_total` non-zero only in loop tests +- latency p95 within agreed threshold (target < 3s for local adapters) diff --git a/runbooks/prime-nextcloud-setup.md b/runbooks/prime-nextcloud-setup.md new file mode 100644 index 0000000..c28455d --- /dev/null +++ b/runbooks/prime-nextcloud-setup.md @@ -0,0 +1,80 @@ +# Prime ↔ Nextcloud Talk Setup Runbook + +## Goal +Set up Prime as a Nextcloud Talk bot in the shared room, with stable secrets in Kubernetes and a human-readable bot name. + +## Source of truth +- Kubernetes namespace: `shard` +- Secrets: + - `cred-nextcloud-prime` + - `cred-nextcloud-shard` +- ConfigMap: + - `server-roles` + +## Required secret keys +From `cred-nextcloud-prime`: +- `NEXTCLOUD_BASE_URL` +- `NEXTCLOUD_USERNAME` +- `NEXTCLOUD_APP_PASSWORD` +- `NEXTCLOUD_TALK_BOT_SECRET` +- `NEXTCLOUD_TALK_WEBHOOK_PUBLIC_URL` + +## Verify Nextcloud auth (Prime account) +```bash +curl -u "$NEXTCLOUD_USERNAME:$NEXTCLOUD_APP_PASSWORD" \ + -H "OCS-APIRequest: true" \ + "$NEXTCLOUD_BASE_URL/ocs/v1.php/cloud/user" +``` +Expected: OCS status `ok` and user info for `Prime`. + +## Inspect Talk bots on server +```bash +php occ talk:bot:list --output json_pretty +``` + +## Inspect bots in a room +```bash +php occ talk:bot:list --output json_pretty +``` + +## Rename behavior caveat +Nextcloud Talk bot names are not edited in place via `occ`. +If a bot was created as `OpenClaw Prime`, rename requires: +1. remove bot from room +2. uninstall bot +3. reinstall bot with desired name (same webhook + secret) +4. set up bot in room again + +## Rename + rebind procedure (example room token `gnrm73b4`) +```bash +# Find old ID +php occ talk:bot:list --output json | jq -r '.[] | select(.name=="OpenClaw Prime") | .id' + +# Remove from room +php occ talk:bot:remove gnrm73b4 + +# Uninstall old bot +php occ talk:bot:uninstall + +# Install new bot with desired name +php occ talk:bot:install "Prime" "$NEXTCLOUD_TALK_BOT_SECRET" "$NEXTCLOUD_TALK_WEBHOOK_PUBLIC_URL" \ + -f webhook -f response -f reaction + +# Find new ID and add to room +php occ talk:bot:list --output json | jq -r '.[] | select(.name=="Prime") | .id' +php occ talk:bot:setup gnrm73b4 + +# Verify +php occ talk:bot:list gnrm73b4 --output json_pretty +``` + +## Current known room +- `https://cloud.aeternalisgames.com/call/gnrm73b4` + +## Current known state (2026-03-13) +- Room `gnrm73b4` has bot name `Prime` attached (webhook/response/reaction). +- Prime user account also exists in Nextcloud with display name `Prime`. + +## Ops notes +- `cred-nextcloud-shard` credential set may not be valid for OCS API auth; use `cred-nextcloud-prime` for Prime Talk integration checks. +- Keep all credential values in k8s secrets only; do not copy raw secrets to git or chat.