memory: sync 2026-03-13 17:36 UTC

This commit is contained in:
Shard
2026-03-13 17:36:22 +00:00
parent 00c464a853
commit 9a20658ff1
9 changed files with 997 additions and 0 deletions
+1
View File
@@ -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.
+50
View File
@@ -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.
+175
View File
@@ -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
+158
View File
@@ -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
+73
View File
@@ -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)
+88
View File
@@ -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
+278
View File
@@ -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 <id>` 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
+94
View File
@@ -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)
+80
View File
@@ -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 <ROOM_TOKEN> --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 <OLD_ID> gnrm73b4
# Uninstall old bot
php occ talk:bot:uninstall <OLD_ID>
# 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 <NEW_ID> 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.