memory: sync 2026-03-13 17:36 UTC
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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)
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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)
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user