claude-code-swarm 0.3.2 → 0.3.4

package/references/openhive/.claude/settings.json

@@ -1,6 +0,0 @@
-{
-  "attribution": {
-    "commit": "",
-    "pr": ""
-  }
-}

package/references/openhive/.dockerignore

@@ -1,54 +0,0 @@
-# Dependencies
-node_modules
-src/web/node_modules
-
-# Build output (will be rebuilt in container)
-dist
-
-# Data directories (should be mounted as volumes)
-data
-uploads
-*.db
-*.db-wal
-*.db-shm
-
-# Git
-.git
-.gitignore
-
-# Documentation (not needed in container)
-*.md
-!README.md
-docs/
-
-# Logs
-logs
-*.log
-
-# Environment files (secrets should be passed via env vars)
-.env*
-!.env.example
-
-# Deployment configs (not needed inside container)
-docker-compose*.yml
-Dockerfile*
-fly.toml
-render.yaml
-railway.toml
-railway.json
-ecosystem.config.js
-deploy/
-
-# Development
-coverage
-.nyc_output
-.vscode
-.idea
-*.swp
-*.swo
-.DS_Store
-
-# Tests
-**/*.test.ts
-**/*.spec.ts
-__tests__

package/references/openhive/.github/workflows/docker.yml

@@ -1,52 +0,0 @@
-name: Build & Push Docker Image
-
-on:
-  push:
-    tags: ['v*']
-  workflow_dispatch:
-
-env:
-  REGISTRY: ghcr.io
-  IMAGE_NAME: ${{ github.repository }}
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: docker/setup-buildx-action@v3
-
-      - name: Log in to GHCR
-        uses: docker/login-action@v3
-        if: github.event_name != 'pull_request'
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Extract metadata
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          tags: |
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=sha,prefix=
-            type=raw,value=latest,enable={{is_default_branch}}
-
-      - name: Build and push
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          platforms: linux/amd64
-          push: ${{ github.event_name != 'pull_request' }}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max

package/references/openhive/.sudocode/issues.jsonl

@@ -1,24 +0,0 @@
-{"id":"i-5nl8","uuid":"635db055-4a70-4507-aa34-be71b96a5c1c","title":"Define MAP sync message types","content":"\nDefine the shared `memory:sync` and `skill:sync` message type interfaces that both OpenHive and swarms use.\n\n```typescript\ntype MapSyncMessage = {\n  type: \"memory:sync\" | \"skill:sync\";\n  resource_id: string;       // syncable_resources ID\n  agent_id: string;          // who pushed\n  commit_hash: string;       // git commit\n  timestamp: string;         // ISO 8601\n}\n```\n\nThis is the contract between swarms and OpenHive. Decide where these types live (shared package, or duplicated in each project).\n\nImplements [[s-78fe]].\n","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-20 08:38:13","updated_at":"2026-02-20 10:30:50","closed_at":"2026-02-20 10:30:50","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-5nl8","from_type":"issue","to":"i-52t0","to_type":"issue","type":"blocks"},{"from":"i-5nl8","from_type":"issue","to":"i-66ra","to_type":"issue","type":"blocks"},{"from":"i-5nl8","from_type":"issue","to":"s-78fe","to_type":"spec","type":"implements"}],"tags":["MAP","sync","types"],"feedback":[{"id":"1ddbae83-ac92-482b-a942-08d31145ea3c","from_id":"i-5nl8","to_id":"s-78fe","feedback_type":"comment","content":"Added `MapSyncMessage` interface and `MapSyncMessageType` to `src/map/types.ts`. Added `memory:sync` and `skill:sync` to `WSEventType` in `src/types.ts`. Types live in the OpenHive package alongside other MAP types — swarm implementations will import or duplicate the interface.","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-20T10:30:49.974Z","updated_at":"2026-02-20T10:30:49.974Z"}]}
-{"id":"i-66ra","uuid":"ad5642a7-3934-40b6-96c8-838a938bff40","title":"OpenHive: Subscribe to swarm MAP endpoints for sync messages","content":"\nWhen a swarm registers via `POST /map/swarms`, OpenHive should subscribe to the swarm's `map_endpoint` using the declared `map_transport` (websocket / http-sse / ndjson).\n\nOpenHive filters for `memory:sync` and `skill:sync` message types. On receiving either:\n\n1. **Bookkeeping** — update `syncable_resources` sync state:\n   - `updateResourceSyncState(resource_id, commit_hash, agent_id)`\n   - `createSyncEvent({ resource_id, commit_hash, pusher: agent_id, ... })`\n2. **WebSocket broadcast** — emit on `resource:{type}:{id}` channel for web UI / non-MAP clients\n\nThis replaces webhooks as the primary sync signal for MAP-aware swarms. Webhooks remain as a parallel path for non-MAP git pushes.\n\nDepends on [[i-5nl8]] for message type definitions.\nImplements [[s-78fe]].\n","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-20 08:38:28","updated_at":"2026-02-20 10:33:46","closed_at":"2026-02-20 10:33:46","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-66ra","from_type":"issue","to":"i-54gb","to_type":"issue","type":"blocks"},{"from":"i-66ra","from_type":"issue","to":"s-78fe","to_type":"spec","type":"implements"}],"tags":["MAP","openhive","sync"],"feedback":[{"id":"87c7d177-89a5-460c-985e-b296a9189c50","from_id":"i-66ra","to_id":"s-78fe","feedback_type":"comment","content":"Created `src/map/sync-listener.ts` with:\n- `initMapSyncListener()` — connects to all online swarms at startup, subscribes to `mapHubEvents` for new registrations\n- `handleSyncMessage()` — validates resource, updates sync state, creates audit event, broadcasts to local WebSocket channels\n- WebSocket connection management with exponential backoff reconnection\n- Wired into `server.ts` startup/shutdown lifecycle (guarded by `config.mapHub.enabled`)\n- Exported from `src/map/index.ts`","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-20T10:33:46.128Z","updated_at":"2026-02-20T10:33:46.128Z"}]}
-{"id":"i-54gb","uuid":"77f3f1ee-989f-4146-b400-de733a1ae8af","title":"OpenHive: Relay sync messages to subscribed swarms","content":"\nAfter OpenHive receives a `memory:sync` or `skill:sync` message from a swarm, it needs to relay the message to all swarms that are subscribed to that resource.\n\nFlow:\n1. Extract `resource_id` from the received message\n2. Look up `resource_subscriptions` for that resource\n3. Identify which swarms those subscribed agents belong to (agent → swarm mapping via `map_swarms.owner_agent_id` or `map_nodes`)\n4. Send the message to each relevant swarm's `map_endpoint` using the swarm's declared `map_transport`\n5. Skip sending back to the originating swarm\n\nDepends on [[i-7ahu]] (inbound subscription must work first).\nImplements [[s-78fe]].\n","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-20 08:38:32","updated_at":"2026-02-20 10:34:58","closed_at":"2026-02-20 10:34:58","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-54gb","from_type":"issue","to":"i-8qr1","to_type":"issue","type":"blocks"},{"from":"i-54gb","from_type":"issue","to":"s-78fe","to_type":"spec","type":"implements"}],"tags":["MAP","openhive","sync"],"feedback":[{"id":"94b2592c-541d-4e09-bc1a-69c48e9ce475","from_id":"i-54gb","to_id":"s-78fe","feedback_type":"comment","content":"Added relay logic to `src/map/sync-listener.ts`:\n- `relaySyncMessage()` — looks up resource subscribers, maps subscriber agents to their online swarms via `findSwarmsByOwnerAgentIds()`, sends the message to each swarm's open WebSocket connection (skipping the source swarm)\n- Added `findSwarmsByOwnerAgentIds()` to `src/db/dal/map.ts` — queries online swarms owned by a set of agent IDs\n- Relay is called from `handleSyncMessage()` after bookkeeping completes","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-20T10:34:58.068Z","updated_at":"2026-02-20T10:34:58.068Z"}]}
-{"id":"i-52t0","uuid":"9774bb8d-da29-48e2-91dd-007d8061af17","title":"Swarm: Emit memory:sync and skill:sync after tool operations","content":"\nThe swarm runtime should emit MAP sync messages on its own MAP endpoint after minimem or skill-tree push operations.\n\n```\nswarm.on('minimem:pushed', (result) => {\n  swarm.map.broadcast({\n    type: 'memory:sync',\n    resource_id: result.resource_id,\n    agent_id: swarm.agent_id,\n    commit_hash: result.commit_hash,\n    timestamp: new Date().toISOString()\n  });\n});\n\nswarm.on('skilltree:pushed', (result) => {\n  swarm.map.broadcast({\n    type: 'skill:sync',\n    resource_id: result.resource_id,\n    agent_id: swarm.agent_id,\n    commit_hash: result.commit_hash,\n    timestamp: new Date().toISOString()\n  });\n});\n```\n\nThe swarm needs to know the `resource_id` for each local memory directory / skill repo. This mapping is part of the swarm's configuration (which local dirs correspond to which OpenHive resources).\n\nAn agent/swarm can have multiple memory and skill repos — each maps to a different `resource_id`.\n\nDepends on [[i-5nl8]] for message type definitions.\nImplements [[s-78fe]].\n","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-20 08:38:38","updated_at":"2026-02-20 10:36:48","closed_at":"2026-02-20 10:36:48","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-52t0","from_type":"issue","to":"s-78fe","to_type":"spec","type":"implements"}],"tags":["MAP","swarm","sync"],"feedback":[{"id":"887847f3-c3ae-4dd4-8fcb-009f5187a9b5","from_id":"i-52t0","to_id":"s-78fe","feedback_type":"comment","content":"Created `src/map/sync-client.ts` — a client library for swarm runtimes to participate in MAP sync. Provides:\n- `emitMemorySync()` / `emitSkillSync()` — broadcast sync messages to connected clients (including OpenHive's sync listener)\n- `handleIncomingConnection()` — register WebSocket clients connecting to the swarm's MAP endpoint\n- Exported as `MapSyncClient` from `src/map/index.ts`\n\nSince the swarm runtime (OpenSwarm) is a separate project, this module lives in OpenHive as an importable SDK. Swarm runtimes wire it into their tool lifecycle:\n```typescript\nconst client = new MapSyncClient({ agent_id, hub_ws_url, owned_resources });\nclient.emitMemorySync({ resource_id: 'res_abc', commit_hash: 'abc123' });\n```","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-20T10:36:47.885Z","updated_at":"2026-02-20T10:36:47.885Z"}]}
-{"id":"i-8qr1","uuid":"6f6c65f0-a8a2-4a20-b835-e49f8f6583b5","title":"Swarm: Handle received sync messages and trigger tool pulls","content":"\nWhen a swarm receives a `memory:sync` or `skill:sync` message (relayed by OpenHive), it should trigger the appropriate tool operation:\n\n```\nswarm.map.on('memory:sync', (msg) => {\n  if (msg.agent_id === swarm.agent_id) return;  // ignore own messages\n  const resource = swarm.getSubscribedResource(msg.resource_id);\n  if (!resource) return;\n  swarm.minimem.pull(resource.git_remote_url);\n  swarm.minimem.reindex(resource.local_dir);\n});\n\nswarm.map.on('skill:sync', (msg) => {\n  if (msg.agent_id === swarm.agent_id) return;\n  const resource = swarm.getSubscribedResource(msg.resource_id);\n  if (!resource) return;\n  swarm.skillTree.refreshRemote(resource.remote_name);\n});\n```\n\nThe swarm maintains a mapping of subscribed `resource_id` → local directory / remote name so it knows where to pull content into.\n\nDepends on [[i-cvge]] (OpenHive relay must work to deliver messages).\nImplements [[s-78fe]].\n","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-20 08:38:44","updated_at":"2026-02-20 10:37:00","closed_at":"2026-02-20 10:37:00","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-8qr1","from_type":"issue","to":"s-78fe","to_type":"spec","type":"implements"}],"tags":["MAP","swarm","sync"],"feedback":[{"id":"5b654b46-b5ec-4d12-a120-d9e0d5f1b3df","from_id":"i-8qr1","to_id":"s-78fe","feedback_type":"comment","content":"Covered by `MapSyncClient` in `src/map/sync-client.ts`:\n- `onMemorySync(handler)` / `onSkillSync(handler)` — register callbacks for incoming sync messages\n- `handleIncomingSync()` — filters by agent_id (ignores own), matches `resource_id` to `subscribed_resources`, dispatches to registered handlers\n- `connectToHub()` — connects to OpenHive's WebSocket endpoint to receive relayed messages\n- Reconnection with exponential backoff\n\nUsage:\n```typescript\nconst client = new MapSyncClient({ agent_id, hub_ws_url, subscribed_resources: [...] });\nclient.onMemorySync((msg, resource) => {\n  minimem.pull(resource.git_remote_url);\n  minimem.reindex(resource.local_dir);\n});\nclient.onSkillSync((msg, resource) => {\n  skillTree.refreshRemote(resource.local_dir);\n});\nclient.start();\n```","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-20T10:37:00.288Z","updated_at":"2026-02-20T10:37:00.288Z"}]}
-{"id":"i-arzo","uuid":"bf2364ba-bce9-450c-96af-a9ff91285061","title":"Swarm: Polling fallback for missed sync messages","content":"\nSince MAP messages are fire-and-forget with no delivery guarantees, swarms need a polling loop to catch up on missed messages (e.g., after being offline).\n\n```\nswarm.startPollingLoop({\n  interval: 60_000,  // configurable\n  onUpdate: (resource, newCommit) => {\n    // Same pull logic as receiving a MAP message\n  }\n});\n```\n\nPolling options:\n- **Git remote ref check** — compare local HEAD vs remote HEAD for each subscribed resource\n- **OpenHive's existing `POST /resources/:id/check-updates`** — checks remote git ref and returns whether there are updates\n\nThe swarm owns its polling cadence. This is independent of MAP message delivery and works even if OpenHive is also offline.\n\nImplements [[s-78fe]].\n","status":"closed","priority":2,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-20 08:38:50","updated_at":"2026-02-20 10:38:05","closed_at":"2026-02-20 10:38:05","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-arzo","from_type":"issue","to":"s-78fe","to_type":"spec","type":"implements"}],"tags":["MAP","polling","swarm","sync"],"feedback":[{"id":"215904be-2599-413b-9e18-de37219f0557","from_id":"i-arzo","to_id":"s-78fe","feedback_type":"comment","content":"Implemented polling fallback in `MapSyncClient`:\n- Added `PollChecker` callback type — consumer provides a function that checks resources for updates (git ls-remote, OpenHive API, etc.)\n- `runPollCycle()` calls the checker, synthesizes `MapSyncMessage` objects for each update, dispatches through the same `onMemorySync`/`onSkillSync` handlers as real-time messages\n- Initial poll runs on `start()` to catch up immediately after coming online\n- Guard against concurrent poll cycles via `this.polling` flag\n\nUsage:\n```typescript\nconst client = new MapSyncClient({\n  agent_id: 'agent-a',\n  subscribed_resources: [...],\n  poll_interval_ms: 60_000,\n  poll_checker: async (resources) => {\n    // Check git remote refs, return those with new commits\n    return [{ resource_id: 'res_abc', commit_hash: 'new123' }];\n  },\n});\n```","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-20T10:38:05.486Z","updated_at":"2026-02-20T10:38:05.486Z"}]}
-{"id":"i-3dvd","uuid":"831a76dc-878a-482a-a0e5-416ab7ec49fd","title":"Add bridge database schema (bridge_configs, channel_mappings, proxy_agents, message_mappings)","content":"Add the four new tables to the database schema as a new migration:\n\n**Tables:**\n\n1. `bridge_configs` — bridge instance configuration (name, platform, transport_mode, credentials_encrypted, status, error_message, owner_agent_id)\n2. `bridge_channel_mappings` — platform channel → hive mapping (bridge_id, platform_channel_id, platform_channel_name, hive_name, direction, thread_mode)\n3. `bridge_proxy_agents` — external user → OpenHive agent mapping (bridge_id, platform_user_id, agent_id, platform_display_name, platform_avatar_url)\n4. `bridge_message_mappings` — platform message → post/comment mapping for thread tracking (bridge_id, platform_message_id, platform_channel_id, post_id, comment_id)\n\nSee spec [[s-9mbr]] for full DDL. Follow existing schema migration pattern in `src/db/schema.ts`. Add appropriate indexes on foreign keys and unique constraints.","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-21 04:52:11","updated_at":"2026-02-21 05:10:07","closed_at":"2026-02-21 05:10:07","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-3dvd","from_type":"issue","to":"i-6wrk","to_type":"issue","type":"blocks"},{"from":"i-3dvd","from_type":"issue","to":"s-9mbr","to_type":"spec","type":"implements"}],"tags":["bridge","database","schema"],"feedback":[{"id":"430e64a4-8e46-4026-9c7d-c3fbb0a95c31","from_id":"i-3dvd","to_id":"s-9mbr","feedback_type":"comment","content":"Created `src/bridge/schema.ts` with 4 tables: `bridge_configs`, `bridge_channel_mappings`, `bridge_proxy_agents`, `bridge_message_mappings`. Registered as schema migration v17 in `src/db/index.ts`. All existing DB tests pass.","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-21T05:10:10.900Z","updated_at":"2026-02-21T05:10:10.900Z"}]}
-{"id":"i-1jbt","uuid":"881cb320-b8c8-466a-916b-02126a39bcf4","title":"Define bridge adapter interface and shared types","content":"Create `src/bridge/types.ts` with the TypeScript interfaces and types for the bridge system:\n\n- `BridgeAdapter` interface — `connect()`, `messages()`, `send()`, `disconnect()`\n- `AdapterConfig` — mode, credentials, channelMappings, webhookBaseUrl\n- `InboundMessage` — normalized inbound message with platformMessageId, author, content, thread, mentions, platformMeta\n- `OutboundMessage` — text, attachments, replyTo\n- `PlatformDestination` — platformChannelId, threadId\n- `Attachment` — type, url, name, mimeType\n- `ChannelMapping` — matches the DB table shape\n- `BridgeConfig` — matches the DB table shape\n- `BridgeStatus` — connecting, connected, error, disconnected\n- `RunningBridge` — runtime state for an active bridge\n\nExport from `src/bridge/index.ts`. These types are consumed by the bridge manager, adapters, and API routes.","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-21 04:52:17","updated_at":"2026-02-21 05:10:08","closed_at":"2026-02-21 05:10:08","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-1jbt","from_type":"issue","to":"i-6dtg","to_type":"issue","type":"blocks"},{"from":"i-1jbt","from_type":"issue","to":"i-6wrk","to_type":"issue","type":"blocks"},{"from":"i-1jbt","from_type":"issue","to":"s-9mbr","to_type":"spec","type":"implements"}],"tags":["bridge","types"],"feedback":[{"id":"9c91505c-5b90-410c-8324-4d534d2edadd","from_id":"i-1jbt","to_id":"s-9mbr","feedback_type":"comment","content":"Created `src/bridge/types.ts` with all interfaces: `BridgeAdapter`, `InboundMessage`, `OutboundMessage`, `PlatformDestination`, `BridgeConfig`, `ChannelMapping`, `ProxyAgent`, `MessageMapping`, `BridgePostMetadata`, and API input types. Exported via `src/bridge/index.ts`.","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-21T05:10:13.063Z","updated_at":"2026-02-21T05:10:13.063Z"}]}
-{"id":"i-8lix","uuid":"489e0119-fd79-4dad-87f9-772037bef329","title":"Add bridge instance configuration to OpenHive config","content":"Add bridge configuration to the OpenHive instance config schema:\n\n```typescript\nbridge: {\n  enabled: boolean;             // master toggle, default false\n  maxBridges: number;           // limit on concurrent bridges, default 10\n  credentialEncryptionKey?: string; // override; defaults to derived from instance secret\n  webhookBaseUrl?: string;      // public URL for webhook mode\n}\n```\n\nUpdate the config type definitions, defaults, and validation. The bridge feature should be disabled by default.","status":"closed","priority":2,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-21 04:52:20","updated_at":"2026-02-21 05:11:16","closed_at":"2026-02-21 05:11:16","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-8lix","from_type":"issue","to":"i-3w9k","to_type":"issue","type":"blocks"},{"from":"i-8lix","from_type":"issue","to":"s-9mbr","to_type":"spec","type":"implements"}],"tags":["bridge","config"]}
-{"id":"i-6wrk","uuid":"580f38eb-38ce-4876-bbbd-60294447e083","title":"Implement bridge DAL (data access layer) for bridge tables","content":"Create `src/db/dal/bridge.ts` with data access functions for the bridge tables. Follow the existing DAL pattern used by other modules (e.g., `src/db/dal/map.ts`).\n\n**Functions needed:**\n\nBridge configs:\n- `createBridge(config)` — insert new bridge config\n- `getBridge(id)` — get bridge by ID\n- `listBridges(ownerId?)` — list bridges, optionally filtered by owner\n- `updateBridge(id, updates)` — update bridge config (status, credentials, etc.)\n- `deleteBridge(id)` — delete bridge and cascade to mappings/proxy agents\n\nChannel mappings:\n- `addChannelMapping(bridgeId, mapping)` — add a channel mapping\n- `getChannelMappings(bridgeId)` — list mappings for a bridge\n- `getChannelMappingByPlatformChannel(bridgeId, platformChannelId)` — lookup for inbound routing\n- `getChannelMappingsByHive(bridgeId, hiveName)` — lookup for outbound routing\n- `deleteChannelMapping(id)` — remove a mapping\n\nProxy agents:\n- `getOrCreateProxyAgent(bridgeId, platformUser)` — find existing or create new proxy agent\n- `getProxyAgentByPlatformUser(bridgeId, platformUserId)` — lookup\n- `listProxyAgents(bridgeId)` — list all proxy agents for a bridge\n\nMessage mappings:\n- `recordMessageMapping(mapping)` — insert message mapping\n- `getMessageMapping(bridgeId, platformMessageId)` — lookup for thread resolution\n- `getMessageMappingByPost(bridgeId, postId)` — reverse lookup for outbound thread tracking\n\nDepends on: bridge schema issue, bridge types issue.","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-21 04:52:28","updated_at":"2026-02-21 05:14:20","closed_at":"2026-02-21 05:14:20","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-6wrk","from_type":"issue","to":"i-2zrs","to_type":"issue","type":"blocks"},{"from":"i-6wrk","from_type":"issue","to":"i-9w7a","to_type":"issue","type":"blocks"},{"from":"i-6wrk","from_type":"issue","to":"s-9mbr","to_type":"spec","type":"implements"}],"tags":["bridge","dal","database"]}
-{"id":"i-11ra","uuid":"6623868d-9946-4342-9f09-abe846d5895c","title":"Implement credential encryption for bridge configs","content":"Implement encryption/decryption for bridge platform credentials stored in `bridge_configs.credentials_encrypted`.\n\n- Use AES-256-GCM for symmetric encryption\n- Key derived from `config.bridge.credentialEncryptionKey` or fallback to instance secret\n- `encryptCredentials(credentials: Record<string, string>, key: string): string` — returns base64-encoded ciphertext with IV and auth tag\n- `decryptCredentials(encrypted: string, key: string): Record<string, string>` — returns plaintext credentials\n- Credentials should never appear in logs or API responses (redact in bridge GET endpoints)\n\nCreate as `src/bridge/credentials.ts`.","status":"closed","priority":2,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-21 04:52:33","updated_at":"2026-02-21 05:11:17","closed_at":"2026-02-21 05:11:17","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-11ra","from_type":"issue","to":"i-3w9k","to_type":"issue","type":"blocks"},{"from":"i-11ra","from_type":"issue","to":"s-9mbr","to_type":"spec","type":"implements"}],"tags":["bridge","security"]}
-{"id":"i-11xs","uuid":"e79d26cf-92ac-4d34-9db2-6de760f368fc","title":"Implement mention extraction for bridge inbound messages","content":"Implement the mention extraction logic that scans inbound message text for `@name` patterns and populates the `mentions` array on `InboundMessage`.\n\n**Behavior:**\n- Scan message text for `@name` patterns (word boundary delimited)\n- Each adapter may also provide platform-native mentions (e.g., Slack `<@U0XYZ789>`) which the adapter resolves to display names before passing to the bridge core\n- The bridge core extracts `@name` mentions from the text and deduplicates with any adapter-provided mentions\n- Mentions are stored as-is (no validation against known agent/swarm names)\n- Mentions are included in post metadata: `{ mentions: [\"infra-swarm\", \"agent-claude\"] }`\n\nCreate as a utility function in `src/bridge/mentions.ts`:\n- `extractMentions(text: string, adapterMentions?: string[]): string[]`\n\nPer spec [[s-9mbr]] Message Routing section — the bridge annotates but does not route. No swarm registry lookup.","status":"closed","priority":2,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-21 04:52:39","updated_at":"2026-02-21 05:11:18","closed_at":"2026-02-21 05:11:18","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-11xs","from_type":"issue","to":"i-9w7a","to_type":"issue","type":"blocks"},{"from":"i-11xs","from_type":"issue","to":"s-9mbr","to_type":"spec","type":"implements"}],"tags":["bridge","routing"]}
-{"id":"i-9w7a","uuid":"176cb54a-85ff-4fad-8381-7c462f13e1ef","title":"Implement inbound message pipeline (platform → OpenHive)","content":"Implement the core inbound pipeline that processes normalized `InboundMessage` objects from adapters and creates posts/comments in OpenHive.\n\n**Pipeline steps** (per spec [[s-9mbr]] Inbound Flow):\n\n1. Resolve channel mapping — lookup `(bridge_id, platformChannelId)` in `bridge_channel_mappings`, skip if no mapping or direction is `outbound`\n2. Resolve or create proxy agent — lookup/create via bridge DAL `getOrCreateProxyAgent()`\n3. Extract mentions — call `extractMentions()` on message text\n4. Determine post vs. comment based on `thread_mode`:\n   - `post_per_message`: top-level = post, thread reply = comment (lookup parent via `bridge_message_mappings`)\n   - `single_thread`: always comment on pinned post\n   - `explicit_only`: check trigger pattern, skip non-matching\n5. Create post or comment via OpenHive API/DAL (using proxy agent as author)\n6. Set bridge metadata on post: `{ bridge, platform_message_id, platform_channel_id, mentions }`\n7. Record message mapping in `bridge_message_mappings`\n8. OpenHive's existing broadcast handles the WebSocket notification\n\nCreate as `src/bridge/inbound.ts` with a `processInboundMessage(bridgeId, message)` function.\n\nDepends on: bridge DAL, mention extraction, bridge types.","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-21 04:52:48","updated_at":"2026-02-21 05:21:36","closed_at":"2026-02-21 05:21:36","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-9w7a","from_type":"issue","to":"i-3w9k","to_type":"issue","type":"blocks"},{"from":"i-9w7a","from_type":"issue","to":"s-9mbr","to_type":"spec","type":"implements"}],"tags":["bridge","pipeline"],"feedback":[{"id":"2115c11d-06f9-40e2-8a8d-c24c72cb5985","from_id":"i-9w7a","to_id":"s-9mbr","feedback_type":"comment","content":"Implemented inbound pipeline in `src/bridge/inbound.ts` with `processInboundMessage(bridgeId, message)`. Handles all three thread modes (post_per_message, single_thread, explicit_only). Creates proxy agents automatically on first message from a platform user. Extracts mentions and broadcasts to WebSocket. 16 tests covering skip conditions, post/comment creation, proxy agent reuse, thread replies, mention extraction, message mapping, and title truncation.","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-21T05:21:30.899Z","updated_at":"2026-02-21T05:21:30.899Z"}]}
-{"id":"i-2zrs","uuid":"3d21241c-1ed1-4408-900d-24a3431c020a","title":"Implement outbound message pipeline (OpenHive → platform)","content":"Implement the outbound pipeline that subscribes to OpenHive WebSocket channels for mapped hives and relays new posts/comments back to the external platform.\n\n**Pipeline steps** (per spec [[s-9mbr]] Outbound Flow):\n\n1. Subscribe to WebSocket channels for all mapped hives (`hive:{name}`)\n2. On `new_post` or `new_comment` event, check:\n   a. Is the author a proxy agent owned by this bridge? Skip (avoid echo)\n   b. Is the channel mapping direction `inbound`? Skip (read-only)\n   c. Does the post/comment have bridge metadata from this bridge? Skip (avoid echo)\n3. Resolve platform destination — hive → platform channel from mappings\n4. For comments, look up parent post in `bridge_message_mappings` for thread ID\n5. Format outbound message — author name, markdown-to-platform conversion, thread context\n6. Call `adapter.send(destination, message)`\n7. Record outbound message in `bridge_message_mappings` for future thread tracking\n\nCreate as `src/bridge/outbound.ts` with an `OutboundRelay` class that manages the WebSocket subscription and relays events.\n\nDepends on: bridge DAL, bridge types.","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-21 04:52:54","updated_at":"2026-02-21 05:21:37","closed_at":"2026-02-21 05:21:37","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-2zrs","from_type":"issue","to":"i-3w9k","to_type":"issue","type":"blocks"},{"from":"i-2zrs","from_type":"issue","to":"s-9mbr","to_type":"spec","type":"implements"}],"tags":["bridge","pipeline"],"feedback":[{"id":"3255bb77-1dfc-4f1e-90cb-3ae6bba0591d","from_id":"i-2zrs","to_id":"s-9mbr","feedback_type":"comment","content":"Implemented outbound pipeline in `src/bridge/outbound.ts` with `processOutboundEvent(bridgeConfig, mappings, event)`. Filters proxy agent events (echo prevention), respects channel direction, resolves thread context from message mappings, and formats outbound messages with author attribution. Returns array of OutboundActions for the BridgeManager to dispatch via adapters. 10 tests covering echo prevention, direction filtering, formatting, thread context, and unmapped hives.","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-21T05:21:34.282Z","updated_at":"2026-02-21T05:21:34.282Z"}]}
-{"id":"i-3w9k","uuid":"aaab5c3a-cbaa-48e3-9858-4a8c51127f23","title":"Implement BridgeManager service","content":"Implement the `BridgeManager` class as a server-level service that manages bridge adapter lifecycles.\n\n**Responsibilities:**\n- Load active bridge configs from DB on startup\n- Instantiate correct adapter for each platform\n- Wire adapter message stream to inbound pipeline\n- Create outbound relay (WebSocket subscription) for each bridge\n- Handle adapter reconnection with exponential backoff on error\n- Update bridge status in DB (`active`, `inactive`, `error` + error_message)\n- Expose `startBridge(id)`, `stopBridge(id)`, `stopAll()`, `getBridgeStatus(id)`\n- Respect `config.bridge.maxBridges` limit\n- Graceful shutdown — disconnect all bridges on server stop\n\nCreate as `src/bridge/manager.ts`. This is the main entry point that the server wires into its lifecycle.\n\nDepends on: bridge DAL, inbound pipeline, outbound pipeline, bridge types, credential encryption, bridge config.","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-21 04:53:00","updated_at":"2026-02-21 05:24:09","closed_at":"2026-02-21 05:24:09","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-3w9k","from_type":"issue","to":"i-3z4a","to_type":"issue","type":"blocks"},{"from":"i-3w9k","from_type":"issue","to":"i-7fqi","to_type":"issue","type":"blocks"},{"from":"i-3w9k","from_type":"issue","to":"s-9mbr","to_type":"spec","type":"implements"}],"tags":["bridge","manager"],"feedback":[{"id":"ea3a8288-6036-49f4-94ee-64c948cd29ed","from_id":"i-3w9k","to_id":"s-9mbr","feedback_type":"comment","content":"Implemented BridgeManager in `src/bridge/manager.ts`. Features: adapter registry pattern, startBridge/stopBridge/stopAll lifecycle, credential decryption, message loop with AbortController, exponential backoff reconnection, outbound event relay via `notifyHiveEvent()`, mapping hot-reload, startAll for server startup, max bridges limit enforcement. 18 tests covering start/stop lifecycle, credential handling, error cases, limit enforcement, outbound relay, mapping reload, and startAll.","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-21T05:24:09.505Z","updated_at":"2026-02-21T05:24:09.505Z"}]}
-{"id":"i-3z4a","uuid":"c751164a-6312-4a9a-b72b-c8fbe139a835","title":"Implement bridge API routes","content":"Add API routes for bridge management at `/api/v1/bridges`.\n\n**Endpoints:**\n- `POST /api/v1/bridges` — create bridge config (validate platform, transport_mode, credentials)\n- `GET /api/v1/bridges` — list bridge configs (redact credentials)\n- `GET /api/v1/bridges/:id` — get bridge details (redact credentials)\n- `PUT /api/v1/bridges/:id` — update bridge config\n- `DELETE /api/v1/bridges/:id` — delete bridge (must be stopped first)\n- `POST /api/v1/bridges/:id/start` — start bridge (calls BridgeManager.startBridge)\n- `POST /api/v1/bridges/:id/stop` — stop bridge (calls BridgeManager.stopBridge)\n- `POST /api/v1/bridges/:id/mappings` — add channel mapping\n- `GET /api/v1/bridges/:id/mappings` — list channel mappings\n- `DELETE /api/v1/bridges/:id/mappings/:mid` — remove channel mapping\n- `GET /api/v1/bridges/:id/agents` — list proxy agents for this bridge\n\n**Webhook receiver:**\n- `POST /api/v1/hooks/:platform/:bridge_id` — inbound webhook endpoint for webhook-mode adapters\n\nAuthentication: require authenticated agent, bridge owner or admin only.\n\nCreate as `src/api/routes/bridges.ts`, register in the main route setup.\n\nDepends on: bridge DAL, BridgeManager, credential encryption.","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-21 04:53:06","updated_at":"2026-02-21 05:26:50","closed_at":"2026-02-21 05:26:50","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-3z4a","from_type":"issue","to":"s-9mbr","to_type":"spec","type":"implements"}],"tags":["api","bridge"],"feedback":[{"id":"87ca93f5-160c-436b-a879-4732b332de60","from_id":"i-3z4a","to_id":"s-9mbr","feedback_type":"comment","content":"Implemented bridge API routes in `src/api/routes/bridges.ts`. Endpoints: CRUD for bridges (with credential redaction), start/stop lifecycle, channel mapping management, proxy agent listing. Auth required for all endpoints, owner/admin check for mutations. Registered in `src/api/index.ts` with optional BridgeManager dependency.","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-21T05:26:47.025Z","updated_at":"2026-02-21T05:26:47.025Z"}]}
-{"id":"i-6dtg","uuid":"ddc3746a-a3c8-4ae7-9c3e-9343e1b04637","title":"Implement Slack bridge adapter (Socket Mode + Events API)","content":"Implement the Slack adapter as the first concrete `BridgeAdapter` implementation.\n\n**Outbound mode (Socket Mode):**\n- Use `@slack/socket-mode` package to connect via outbound WebSocket\n- Authenticate with `app_token` (xapp-...) for Socket Mode connection\n- Use `bot_token` (xoxb-...) for Web API calls (sending messages, user info)\n- Receive message events, normalize to `InboundMessage` format\n- Resolve Slack user mentions (`<@U0XYZ789>`) to display names via `users.info` API\n- Extract thread_ts for threading support\n\n**Webhook mode (Events API):**\n- Receive HTTP POST events at `/api/v1/hooks/slack/:bridge_id`\n- Verify Slack signing secret (HMAC-SHA256 with `X-Slack-Signature` header)\n- Handle URL verification challenge\n- Process `message` events, normalize to `InboundMessage`\n\n**Outbound (send):**\n- Use `@slack/web-api` to post messages via `chat.postMessage`\n- Convert markdown to Slack mrkdwn format\n- Support threading via `thread_ts` parameter\n- Include author attribution in message\n\nCreate as `src/bridge/adapters/slack.ts`.\n\nDepends on: bridge adapter interface/types.","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-21 04:53:14","updated_at":"2026-02-21 05:29:07","closed_at":"2026-02-21 05:29:07","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-6dtg","from_type":"issue","to":"s-9mbr","to_type":"spec","type":"implements"}],"tags":["adapter","bridge","slack"],"feedback":[{"id":"592d87d9-d31d-4948-8346-42fa9f5a7526","from_id":"i-6dtg","to_id":"s-9mbr","feedback_type":"comment","content":"Implemented Slack adapter in `src/bridge/adapters/slack.ts`. Features: Socket Mode (outbound transport) via @slack/socket-mode, Web API message sending via @slack/web-api, Slack mention resolution (`<@U...>` → display names), thread_ts threading support, markdown→mrkdwn conversion, user info caching, pushInboundMessage for webhook mode, file attachment normalization. Installed @slack/socket-mode and @slack/web-api packages. 13 tests covering connection modes, message push/consume, sending, threading, markdown conversion, and disconnect behavior.","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-21T05:29:07.158Z","updated_at":"2026-02-21T05:29:07.158Z"}]}
-{"id":"i-7fqi","uuid":"d4bc52ee-406d-4822-b513-9d95b976b936","title":"Wire BridgeManager into server startup/shutdown lifecycle","content":"Integrate the BridgeManager into the OpenHive server lifecycle in `src/server.ts`.\n\n- Instantiate BridgeManager if `config.bridge.enabled` is true\n- On server start: call `bridgeManager.loadAndStartActiveBridges()` to resume active bridges\n- On server shutdown: call `bridgeManager.stopAll()` for graceful disconnect\n- Follow the same pattern as the MAP sync listener and SwarmCraft plugin integration\n\nDepends on: BridgeManager, bridge config.","status":"closed","priority":2,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-21 04:53:18","updated_at":"2026-02-21 05:26:50","closed_at":"2026-02-21 05:26:50","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-7fqi","from_type":"issue","to":"s-9mbr","to_type":"spec","type":"implements"}],"tags":["bridge","server"],"feedback":[{"id":"9eac4f64-ddbc-43c5-ac60-7e99d7105566","from_id":"i-7fqi","to_id":"s-9mbr","feedback_type":"comment","content":"Wired BridgeManager into server lifecycle in `src/server.ts`. Creates BridgeManager when `config.bridge.enabled`, passes to registerRoutes, calls `startAll()` during server start, and `stopAll()` during shutdown. Follows existing SwarmManager/SyncService patterns.","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-21T05:26:49.566Z","updated_at":"2026-02-21T05:26:49.566Z"}]}
-{"id":"i-1lof","uuid":"07e6854a-90fe-4720-835e-eaa2671e5ba5","title":"Define session sync wire format types in openhive-types","content":"Phase 1: Create `packages/openhive-types/src/map-session-sync.ts` with all session sync types (SessionSyncParams, SessionCheckpointSummary, MapSessionSyncMessage, MapSessionContentRequest, MapSessionContentResponse, MapSessionContentChunkMessage) and validation constants. Update `packages/openhive-types/src/index.ts` and `src/map/types.ts` with re-exports. Follow existing patterns from `map-sync.ts` and `map-coordination.ts`.","status":"open","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-03-01 20:45:05","updated_at":"2026-03-01 20:45:05","closed_at":null,"parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-1lof","from_type":"issue","to":"i-15eu","to_type":"issue","type":"blocks"},{"from":"i-1lof","from_type":"issue","to":"i-1yvn","to_type":"issue","type":"blocks"},{"from":"i-1lof","from_type":"issue","to":"s-3me1","to_type":"spec","type":"implements"}],"tags":["map","phase-1","types"]}
-{"id":"i-3qeo","uuid":"af59496c-b573-48f5-9fa8-c8886e514e36","title":"Add onCheckpointCommitted callback to sessionlog strategy","content":"Phase 2: Add `onCheckpointCommitted` callback to `ManualCommitStrategyConfig` in `references/sessionlog/src/strategy/manual-commit.ts`. Define `CheckpointCommittedEvent` type. Invoke the callback after `checkpointStore.writeCommitted()` succeeds in `condenseSession()` (~line 675). Export the new type from `references/sessionlog/src/index.ts`. Fire-and-forget with try/catch.","status":"open","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-03-01 20:45:09","updated_at":"2026-03-01 20:45:09","closed_at":null,"parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-3qeo","from_type":"issue","to":"i-9x94","to_type":"issue","type":"blocks"},{"from":"i-3qeo","from_type":"issue","to":"s-3me1","to_type":"spec","type":"implements"}],"tags":["callback","phase-2","sessionlog"]}
-{"id":"i-1yvn","uuid":"52d50929-c180-46a3-b2c0-a26fcf830c6a","title":"Add session sync emission and content request handling to MapSyncClient","content":"Phase 3: Extend `MapSyncClient` in `src/map/sync-client.ts` with: (a) `emitSessionSync()` method, (b) `onContentRequest()` handler registration, (c) `sendContentResponse()` and `sendContentChunk()` helpers, (d) update message handler to recognize `x-openhive/session.content` requests (JSON-RPC with `id` field -- new pattern), (e) widen `broadcast()` to accept session sync messages. Content request handler should read from checkpoint store, check size against 512KB threshold, and either respond inline or stream via chunked base64 JSONL.","status":"blocked","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-03-01 20:45:14","updated_at":"2026-03-01 20:45:40","closed_at":null,"parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-1yvn","from_type":"issue","to":"i-9x94","to_type":"issue","type":"blocks"},{"from":"i-1yvn","from_type":"issue","to":"s-3me1","to_type":"spec","type":"implements"}],"tags":["map","phase-3","sync-client"]}
-{"id":"i-15eu","uuid":"5e8188b3-5019-4228-9150-aa727923afed","title":"Add session sync handling to hub sync listener","content":"Phase 4: Extend `src/map/sync-listener.ts` with: (a) `isSessionSyncMessage()` type guard, (b) `handleSessionSyncMessage()` that stores metadata in syncable_resources, creates audit events, broadcasts to WS channels, (c) update `connectToSwarm()` message handler to dispatch session sync messages, (d) `requestSessionContent()` to send JSON-RPC requests to swarms, (e) pending request tracking with timeout for content responses and chunk reassembly.","status":"blocked","priority":2,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-03-01 20:45:17","updated_at":"2026-03-01 20:45:41","closed_at":null,"parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-15eu","from_type":"issue","to":"i-7w50","to_type":"issue","type":"blocks"},{"from":"i-15eu","from_type":"issue","to":"i-9x94","to_type":"issue","type":"blocks"},{"from":"i-15eu","from_type":"issue","to":"s-3me1","to_type":"spec","type":"implements"}],"tags":["hub","map","phase-4","sync-listener"]}
-{"id":"i-7w50","uuid":"aa4c4b4e-437b-4a75-b4c8-394e9cdafe03","title":"Add hub-side content caching via SessionStorageAdapter","content":"Phase 5: Create `src/map/session-content-cache.ts` with `cacheSessionContent()` and `getCachedContent()` functions that use `getSessionStorage()` to persist fetched checkpoint content locally. Integrate with the pending request handler from Phase 4 so content is cached when received. Check `isSessionStorageInitialized()` before attempting cache operations.","status":"blocked","priority":3,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-03-01 20:45:21","updated_at":"2026-03-01 20:45:43","closed_at":null,"parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-7w50","from_type":"issue","to":"s-3me1","to_type":"spec","type":"implements"}],"tags":["cache","map","phase-5","storage"]}
-{"id":"i-9x94","uuid":"413533ca-fac8-4521-8243-26d1dadb803a","title":"Wire sessionlog checkpoint callback to MAP sync emission","content":"Phase 6: In the swarm hosting bridge (where `createManualCommitStrategy` is called), pass `onCheckpointCommitted` that calls `syncClient.emitSessionSync()`. Also wire `syncClient.onContentRequest()` to read from `checkpointStore.readSessionContent()` and respond inline or with chunked streaming based on size threshold. Map sessionlog types (TokenUsage, Summary) to wire format types (snake_case).","status":"blocked","priority":2,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-03-01 20:45:25","updated_at":"2026-03-01 20:45:41","closed_at":null,"parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-9x94","from_type":"issue","to":"s-3me1","to_type":"spec","type":"implements"}],"tags":["bridge","phase-6","wiring"]}

package/references/openhive/.sudocode/specs.jsonl

@@ -1,4 +0,0 @@
-{"id":"s-78fe","uuid":"38fbad4c-3cea-44ed-bec0-8756a60ccfa8","title":"MAP-Mediated Memory & Skill Sync","file_path":"specs/s-78fe_map_mediated_memory_skill_sync.md","content":"\n# MAP-Mediated Memory & Skill Sync\n\n## Overview\n\nOpenHive serves as a sync center for agent memory (minimem) and skills (skill-tree) using MAP broadcast messages. Rather than requiring specialized sync endpoints or direct tool-level integration, the sync flow is mediated through MAP messages emitted and consumed by swarms. OpenHive participates as a MAP peer — listening to registered swarms and relaying messages to subscribers.\n\n## Design Principles\n\n1. **Swarm emits, tools don't** — minimem and skill-tree are tools with no MAP awareness. The swarm runtime is responsible for emitting sync messages after tool operations and triggering tool operations when sync messages arrive.\n2. **Git is the content store** — MAP messages carry metadata (resource ID, commit hash), not content. Agents pull content from git.\n3. **Fire-and-forget broadcast** — Messages are ephemeral broadcasts with no delivery guarantees, acknowledgment, or ordering. Missed messages are recovered via polling.\n4. **OpenHive is a MAP participant, not a special hub** — It listens to swarm MAP endpoints and relays to subscribers using the same MAP transport. No special publish endpoint.\n5. **Polling as fallback** — Swarms that miss messages poll their subscribed resources (git ref check or OpenHive's existing `check-updates` endpoints) to catch up.\n\n## Component Roles\n\n| Component | Role |\n|---|---|\n| **Swarm** | MAP-aware agent runtime. Emits `memory:sync` / `skill:sync` messages on its MAP endpoint. Subscribes to messages from OpenHive. Triggers tool operations (minimem pull, skill-tree pull) on received messages. Handles its own polling cadence for missed messages. |\n| **minimem** | Tool. Reads/writes/indexes memory files. Pushes to git. No MAP awareness, no sync responsibility. |\n| **skill-tree** | Tool. Manages skills (CRUD, versioning, extraction). Pushes to git. No MAP awareness, no sync responsibility. |\n| **OpenHive** | MAP participant. Subscribes to all registered swarms' MAP endpoints. On receiving `memory:sync` or `skill:sync`, updates its own resource tracking state (bookkeeping) and relays the message to all swarms subscribed to that resource. |\n\n## Message Types\n\nTwo message types for now:\n\n### `memory:sync`\n\nEmitted by a swarm after its minimem instance pushes memory changes to git.\n\n```typescript\n{\n  type: \"memory:sync\",\n  resource_id: string,       // which memory bank (from syncable_resources)\n  agent_id: string,          // who pushed\n  commit_hash: string,       // the commit that was pushed\n  timestamp: string          // ISO 8601\n}\n```\n\n### `skill:sync`\n\nEmitted by a swarm after its skill-tree instance pushes skill changes to git.\n\n```typescript\n{\n  type: \"skill:sync\",\n  resource_id: string,       // which skill repo (from syncable_resources)\n  agent_id: string,          // who pushed\n  commit_hash: string,       // the commit that was pushed\n  timestamp: string          // ISO 8601\n}\n```\n\n## Multiple Repos\n\nAn agent/swarm can have multiple memory and skill repos. Each is a separate `syncable_resource` with its own `resource_id`. The `resource_id` in the message identifies which repo changed. Example:\n\n```\nSwarm A's registered resources:\n  res_abc → memory_bank \"project-alpha-memory\"   (git: github.com/a/alpha-mem)\n  res_def → memory_bank \"personal-memory\"         (git: github.com/a/personal)\n  res_ghi → skill        \"team-skills\"            (git: github.com/team/skills)\n  res_jkl → skill        \"personal-skills\"        (git: github.com/a/my-skills)\n```\n\nEach sync message targets a specific `resource_id`. Subscribers only receive notifications for resources they're subscribed to.\n\n## Sync Flow\n\n### Push Flow (Swarm A pushes changes)\n\n```\n1. Swarm A's minimem writes memory files and pushes to git\n2. Swarm A emits on its MAP endpoint:\n   { type: \"memory:sync\", resource_id: \"res_abc\", agent_id: \"agent-a\", commit_hash: \"def456\", timestamp: \"...\" }\n3. OpenHive is subscribed to Swarm A's MAP endpoint (because Swarm A is a registered swarm)\n4. OpenHive receives the message:\n   a. Updates syncable_resources: last_commit_hash, last_push_by, last_push_at\n   b. Creates resource_sync_events entry (audit trail)\n   c. Looks up resource_subscriptions for res_abc\n   d. Forwards the message to each subscribed swarm's MAP endpoint\n5. Swarm B receives the forwarded message via its MAP endpoint\n6. Swarm B triggers minimem pull for res_abc's git remote URL\n7. Swarm B's minimem re-indexes the updated files\n```\n\n### Missed Message Recovery (Polling)\n\n```\n1. Swarm B comes online after being offline\n2. Swarm B polls its subscribed resources:\n   - Option A: Git remote ref check (compare local HEAD vs remote HEAD)\n   - Option B: OpenHive's existing POST /resources/:id/check-updates endpoint\n3. Detects commit_hash mismatch for res_abc\n4. Pulls from git, re-indexes\n5. Caught up — no event log needed\n```\n\n## OpenHive Behavior\n\n### Inbound (listening to swarms)\n\n- On swarm registration (`POST /map/swarms`), OpenHive subscribes to the swarm's `map_endpoint` using the declared `map_transport` (websocket / http-sse / ndjson)\n- Filters for `memory:sync` and `skill:sync` message types\n- On receiving either:\n  - Updates `syncable_resources` sync state (same as current webhook behavior)\n  - Creates `resource_sync_events` entry\n  - Relays to subscribed swarms (see outbound)\n\n### Outbound (relaying to subscribers)\n\n- Looks up `resource_subscriptions` for the `resource_id` in the received message\n- Identifies which swarms those subscribed agents belong to\n- Sends the message to each relevant swarm's `map_endpoint`\n- Uses the swarm's declared `map_transport` for delivery\n\n### Bookkeeping side effects\n\nWhen OpenHive processes a `memory:sync` or `skill:sync` message, it performs the same state updates that webhooks currently trigger:\n- `updateResourceSyncState(resource_id, commit_hash, agent_id)`\n- `createSyncEvent({ resource_id, commit_hash, pusher: agent_id, ... })`\n- Existing WebSocket broadcast on `resource:{type}:{id}` channels (for web UI / non-MAP clients)\n\nThis means **webhooks become a parallel path, not the primary one**. Swarms that emit MAP messages don't need webhooks. Webhooks remain as a fallback for non-MAP git pushes.\n\n## Swarm Behavior\n\n### On local tool operations\n\nAfter minimem push:\n```\nswarm.on('minimem:pushed', (result) => {\n  swarm.map.broadcast({\n    type: 'memory:sync',\n    resource_id: result.resource_id,\n    agent_id: swarm.agent_id,\n    commit_hash: result.commit_hash,\n    timestamp: new Date().toISOString()\n  });\n});\n```\n\nAfter skill-tree push:\n```\nswarm.on('skilltree:pushed', (result) => {\n  swarm.map.broadcast({\n    type: 'skill:sync',\n    resource_id: result.resource_id,\n    agent_id: swarm.agent_id,\n    commit_hash: result.commit_hash,\n    timestamp: new Date().toISOString()\n  });\n});\n```\n\n### On received MAP messages\n\n```\nswarm.map.on('memory:sync', (msg) => {\n  if (msg.agent_id === swarm.agent_id) return; // ignore own messages\n  const resource = swarm.getSubscribedResource(msg.resource_id);\n  if (!resource) return;\n  swarm.minimem.pull(resource.git_remote_url);\n  swarm.minimem.reindex(resource.local_dir);\n});\n\nswarm.map.on('skill:sync', (msg) => {\n  if (msg.agent_id === swarm.agent_id) return;\n  const resource = swarm.getSubscribedResource(msg.resource_id);\n  if (!resource) return;\n  swarm.skillTree.refreshRemote(resource.remote_name);\n});\n```\n\n### Polling loop\n\n```\nswarm.startPollingLoop({\n  interval: 60_000,  // every 60s\n  onUpdate: (resource, newCommit) => {\n    // Same pull logic as receiving a MAP message\n  }\n});\n```\n\n## Relationship to Existing Infrastructure\n\n| Existing | Relationship |\n|---|---|\n| `syncable_resources` table | Unchanged. Resources are registered here. MAP messages reference `resource_id` from this table. |\n| `resource_subscriptions` table | Unchanged. OpenHive uses this to determine which swarms to relay messages to. |\n| `resource_sync_events` table | Unchanged. OpenHive creates entries here as a side effect of processing MAP messages. |\n| Webhook endpoints (`/webhooks/*`) | Remain as parallel path. Webhooks and MAP messages both update sync state. Webhooks serve non-MAP git pushes. |\n| Polling endpoints (`/resources/check-updates`) | Remain as fallback. Swarms use these when they've been offline and need to catch up. |\n| WebSocket broadcast (`resource:{type}:{id}`) | Remains for web UI and non-MAP clients. OpenHive can still broadcast here as a side effect of processing MAP messages. |\n| `map_swarms` table | Used to look up swarm MAP endpoints for subscribing and relaying. |\n\n## Non-Goals (for now)\n\n- **No content in messages** — messages carry metadata only. Content lives in git.\n- **No request/response** — no \"search across agents' memories\" via MAP.\n- **No event log / persistence** — messages are ephemeral. Polling handles catch-up.\n- **No message ordering** — fire-and-forget. Agents handle eventual consistency via git state.\n- **No granular message types** — just `memory:sync` and `skill:sync`. More specific types (appended, pruned, deprecated, forked) can be added later.\n- **No minimem or skill-tree changes** — these tools stay MAP-unaware. All MAP behavior lives in the swarm runtime.\n","priority":1,"archived":0,"archived_at":null,"created_at":"2026-02-20 08:11:41","updated_at":"2026-02-20 08:11:41","parent_id":null,"parent_uuid":null,"relationships":[],"tags":["architecture","MAP","memory","skills","sync"]}
-{"id":"s-9mbr","uuid":"51735f97-1123-4258-b300-973fd2493950","title":"Channel Bridge: External Platform Integration","file_path":"specs/s-9mbr_channel_bridge_external_platform_integration.md","content":"\n# Channel Bridge: External Platform Integration\n\n## Overview\n\nOpenHive channels currently operate within the OpenHive ecosystem — WebSocket pub/sub for real-time events, REST API for CRUD, and the web UI for human interaction. The Channel Bridge extends this by connecting OpenHive hives to external communication platforms (Slack, Discord, Telegram, WhatsApp), allowing users on those platforms to interact with swarms and participate in hives without using the OpenHive UI directly.\n\nThe primary use case is **human-to-swarm steering**: a user posts a message in Slack, it flows into an OpenHive hive, a swarm picks it up as a task or directive, and the swarm's response flows back to the user on their platform.\n\n## Design Principles\n\n1. **Transport-agnostic adapter interface** — Each platform adapter produces a normalized message stream. The bridge core doesn't know or care whether messages arrived via outbound WebSocket, inbound webhook, or polling. The adapter owns its transport.\n2. **Outbound-first for local deployments** — Adapters prefer outbound connections (connecting *to* the platform) over inbound webhooks, since OpenHive is designed for self-hosting and may run behind NAT/firewalls without a public URL. Platforms that only support inbound webhooks (WhatsApp Cloud API) require a public URL or tunnel.\n3. **Proxy agents for identity** — Each external user is represented as an OpenHive agent. Messages are attributed to the individual, not a generic bridge bot. This preserves authorship for swarm steering.\n4. **Hive is the routing boundary** — Channel mapping determines which hive a message lands in. A Slack channel maps to a hive. Routing to swarms is determined by which hive the swarm watches — the bridge doesn't need to know about swarms.\n5. **Bidirectional by default** — Inbound (platform → OpenHive) and outbound (OpenHive → platform) are both supported. Adapters that only support one direction degrade gracefully.\n6. **Existing infrastructure, not parallel paths** — Bridged messages use the same posts, comments, agents, and WebSocket channels as native OpenHive content. Swarms don't need bridge-specific logic — they just see posts in a hive.\n\n## Transport Abstraction\n\n### The Problem\n\nExternal platforms deliver messages differently:\n- **Slack** can push webhooks (Events API) or deliver over an outbound WebSocket (Socket Mode)\n- **Discord** delivers over an outbound WebSocket (Gateway API) — no webhook mode for messages\n- **Telegram** supports both inbound webhooks and outbound long-polling (`getUpdates`)\n- **WhatsApp (Meta Cloud API)** only supports inbound webhooks — no outbound option\n\nA locally-running OpenHive instance has no public URL, so inbound webhooks don't work without a tunnel or relay.\n\n### Transport Modes\n\nEach adapter supports one or both modes, configured per-bridge instance:\n\n| Mode | Direction | Requires public URL | How it works |\n|---|---|---|---|\n| `outbound` | Bridge connects to platform | No | WebSocket, long-poll, or client library connects out to platform servers |\n| `webhook` | Platform connects to bridge | Yes | Platform POSTs events to a registered URL on the OpenHive server |\n\n### Per-Platform Transport Support\n\n| Platform | `outbound` support | `webhook` support | Notes |\n|---|---|---|---|\n| Slack | Socket Mode (outbound WS) | Events API (inbound POST) | Socket Mode recommended for local |\n| Discord | Gateway API (outbound WS) | — | Always outbound |\n| Telegram | `getUpdates` (outbound poll) | Webhook (inbound POST) | Both officially supported |\n| WhatsApp | — | Webhook (inbound POST) | Meta Cloud API; requires public URL or tunnel for local deployments |\n| Matrix | Appservice (outbound) | — | Connects to homeserver |\n\nWhatsApp is the only supported platform without an outbound transport option. All unofficial libraries that provide outbound WhatsApp connectivity (Baileys, whatsapp-web.js) violate WhatsApp's Terms of Service and are excluded from this design. WhatsApp bridges require either a publicly accessible deployment or a user-provided tunnel/relay.\n\n### Adapter Interface\n\n```typescript\ninterface BridgeAdapter {\n  /** Platform identifier */\n  platform: string;\n\n  /** \n   * Start the adapter. Returns an async iterable of normalized inbound messages.\n   * The adapter handles its own transport internally (WebSocket, polling, webhook listener).\n   */\n  connect(config: AdapterConfig): Promise<void>;\n\n  /**\n   * Stream of inbound messages from the platform.\n   * Each adapter produces these regardless of transport mode.\n   */\n  messages(): AsyncIterable<InboundMessage>;\n\n  /**\n   * Send a message to the platform.\n   * The adapter translates from normalized format to platform-native format.\n   */\n  send(destination: PlatformDestination, message: OutboundMessage): Promise<void>;\n\n  /**\n   * Gracefully disconnect from the platform.\n   */\n  disconnect(): Promise<void>;\n}\n\ninterface AdapterConfig {\n  /** Transport mode */\n  mode: 'outbound' | 'webhook';\n\n  /** Platform-specific credentials */\n  credentials: Record<string, string>;\n\n  /** Channel mappings (platform channel ID → hive name) */\n  channelMappings: ChannelMapping[];\n\n  /** Webhook base URL (only used in webhook mode) */\n  webhookBaseUrl?: string;\n}\n```\n\n## Message Normalization\n\nAll adapters produce and consume a common message format. Platform-specific details are preserved in `platformMeta` for round-tripping (e.g., replying to the correct Slack thread).\n\n### Inbound Message (Platform → OpenHive)\n\n```typescript\ninterface InboundMessage {\n  /** Unique message ID from the platform */\n  platformMessageId: string;\n\n  /** Platform identifier */\n  platform: string;\n\n  /** Platform channel/group/chat ID */\n  platformChannelId: string;\n\n  /** Author info from the platform */\n  author: {\n    platformUserId: string;\n    displayName: string;\n    avatarUrl?: string;\n  };\n\n  /** Message content */\n  content: {\n    text: string;\n    attachments?: Attachment[];\n  };\n\n  /** Threading info */\n  thread?: {\n    /** Platform's thread/reply ID — indicates this is a reply */\n    parentMessageId: string;\n  };\n\n  /** Mentions extracted from the message (see Message Routing) */\n  mentions?: string[];\n\n  /** ISO 8601 timestamp */\n  timestamp: string;\n\n  /** \n   * Platform-specific metadata preserved for round-tripping.\n   * Used when sending responses back to the correct context.\n   */\n  platformMeta: Record<string, unknown>;\n}\n\ninterface Attachment {\n  type: 'image' | 'file' | 'link';\n  url: string;\n  name?: string;\n  mimeType?: string;\n}\n```\n\n### Outbound Message (OpenHive → Platform)\n\n```typescript\ninterface OutboundMessage {\n  /** Message text content (may contain markdown) */\n  text: string;\n\n  /** Attachments to include */\n  attachments?: Attachment[];\n\n  /** If replying to a specific platform message */\n  replyTo?: string;\n}\n\ninterface PlatformDestination {\n  /** Platform channel/group/chat ID to send to */\n  platformChannelId: string;\n\n  /** Optional thread to reply in */\n  threadId?: string;\n}\n```\n\n## Message Routing\n\nRouting determines which swarm or agent receives a bridged message. The bridge uses a two-layer approach: **channel-level routing** as the primary mechanism, with **mention-based annotation** as an optional refinement. The bridge itself does not route to swarms — it delivers messages to hives and annotates them. Swarms decide whether to act.\n\n### Layer 1: Channel-Level Routing (Primary)\n\nThe channel mapping determines which hive a message lands in. Swarms subscribe to specific hives. This means the platform channel a user posts in determines which swarm sees the message.\n\n```\nSlack                    OpenHive                 Swarm\n─────                    ────────                 ─────\n#infra-team         →    hive:infra-team     ←    infra-swarm (watches this hive)\n#research           →    hive:research       ←    research-swarm (watches this hive)\n#general            →    hive:general        ←    (no swarm — human-only discussion)\n#project-alpha      →    hive:project-alpha  ←    alpha-swarm (watches this hive)\n```\n\nUsers route messages by choosing which channel to post in — the same way teams already use Slack naturally. No special syntax or addressing needed.\n\n**One hive, one swarm** is the simplest model: each hive has at most one swarm watching it. If multiple swarms watch the same hive, they self-select based on their own logic (see Layer 2).\n\n### Layer 2: Mention-Based Annotation (Optional)\n\nFor shared channels where multiple swarms or agents are present, users can @mention a specific target. The bridge detects mentions and annotates the post metadata — but does not route. Swarms filter on mentions themselves.\n\n**Detection**: The bridge scans inbound message text for `@name` patterns. Platform-native mentions (e.g., Slack's `<@U0XYZ789>` user mentions) are resolved to display names. Mentions that match known OpenHive agent names or swarm names are extracted.\n\n**Annotation**: Detected mentions are added to the `InboundMessage.mentions` array and stored in the post's metadata:\n\n```typescript\n// Post metadata set by bridge\n{\n  bridge: \"slack\",\n  platform_message_id: \"1708444800.001200\",\n  platform_channel_id: \"C0ABC123\",\n  mentions: [\"infra-swarm\", \"agent-claude\"]\n}\n```\n\n**Swarm behavior**: Swarms can use mentions to decide whether to act:\n\n```\n// Swarm-side filtering (example, not part of bridge spec)\nif (post.metadata.mentions && !post.metadata.mentions.includes(mySwarmName)) {\n  // Message is addressed to someone else, skip\n  return;\n}\n// No mentions = broadcast to all watchers of this hive\nif (!post.metadata.mentions) {\n  // Decide based on own heuristics (keyword match, LLM classification, etc.)\n}\n```\n\n**Convention**: If a message has no mentions, it is treated as a broadcast to all watchers of the hive. If it has mentions, only the mentioned swarms/agents should act. This is a convention enforced by swarms, not by the bridge.\n\n### Routing Summary\n\n| Scenario | How it works |\n|---|---|\n| User posts in `#infra-team` | Message lands in `hive:infra-team`. Infra swarm picks it up. No mentions needed. |\n| User posts in `#ops` mentioning `@infra-swarm` | Message lands in `hive:ops`. Bridge annotates `mentions: [\"infra-swarm\"]`. Infra swarm sees its name, picks it up. Other swarms watching `hive:ops` see they're not mentioned and skip. |\n| User posts in `#ops` with no mention | Message lands in `hive:ops`. All swarms watching `hive:ops` evaluate whether to respond based on their own logic. |\n| User posts in `#general` (no swarm watches) | Message lands in `hive:general`. No swarm picks it up. Humans discuss on OpenHive. |\n\n### What the bridge does NOT do\n\n- **No swarm registry lookup** — the bridge doesn't know which swarms exist or which hives they watch. It just delivers to hives.\n- **No intelligent dispatch** — the bridge doesn't parse message intent, classify tasks, or decide which swarm is best suited. That's swarm-side logic.\n- **No delivery guarantees to swarms** — if no swarm is watching a hive, the message sits as a regular post. The bridge doesn't warn or retry.\n- **No mention validation** — the bridge annotates whatever looks like an @mention. It doesn't verify that the mentioned name corresponds to an actual swarm or agent.\n\n## Channel Mapping\n\nEach bridge instance maps one or more platform channels to OpenHive hives. This mapping is stored in the database and configurable via the admin API.\n\n### Mapping Table: `bridge_channel_mappings`\n\n```sql\nCREATE TABLE bridge_channel_mappings (\n  id TEXT PRIMARY KEY,\n  bridge_id TEXT NOT NULL REFERENCES bridge_configs(id),\n  platform_channel_id TEXT NOT NULL,\n  platform_channel_name TEXT,          -- human-readable, for display\n  hive_name TEXT NOT NULL,             -- target OpenHive hive\n  direction TEXT DEFAULT 'bidirectional',  -- 'inbound' | 'outbound' | 'bidirectional'\n  thread_mode TEXT DEFAULT 'post_per_message', -- see Thread Mapping section\n  created_at TEXT NOT NULL DEFAULT (datetime('now')),\n  updated_at TEXT NOT NULL DEFAULT (datetime('now')),\n  UNIQUE(bridge_id, platform_channel_id)\n);\n```\n\n### Mapping Examples\n\n```\nBridge: \"team-slack\" (platform: slack, mode: outbound)\n  #general        → hive:general         (bidirectional)\n  #project-alpha  → hive:project-alpha   (bidirectional)\n  #announcements  → hive:announcements   (inbound only — read from Slack, don't post back)\n\nBridge: \"ops-telegram\" (platform: telegram, mode: outbound)\n  group:-1001234  → hive:ops-alerts      (bidirectional)\n\nBridge: \"team-whatsapp\" (platform: whatsapp, mode: webhook)\n  group:ABC123    → hive:wa-team         (bidirectional, requires public URL)\n```\n\n## Identity Mapping: Proxy Agents\n\nExternal users are represented as OpenHive agents. The bridge creates these on first encounter and reuses them for subsequent messages.\n\n### Proxy Agent Table: `bridge_proxy_agents`\n\n```sql\nCREATE TABLE bridge_proxy_agents (\n  id TEXT PRIMARY KEY,\n  bridge_id TEXT NOT NULL REFERENCES bridge_configs(id),\n  platform_user_id TEXT NOT NULL,\n  agent_id TEXT NOT NULL REFERENCES agents(id),\n  platform_display_name TEXT,\n  platform_avatar_url TEXT,\n  created_at TEXT NOT NULL DEFAULT (datetime('now')),\n  updated_at TEXT NOT NULL DEFAULT (datetime('now')),\n  UNIQUE(bridge_id, platform_user_id)\n);\n```\n\n### Agent Creation\n\nWhen the bridge encounters a new platform user:\n\n1. Check `bridge_proxy_agents` for existing mapping\n2. If not found, create a new OpenHive agent:\n   - `name`: `{platform}-{sanitized_display_name}` (e.g., `slack-jane-doe`)\n   - `account_type`: `'human'`\n   - `description`: `\"Bridged from {platform}\"`\n   - `avatar_url`: platform avatar if available\n   - `metadata`: `{ bridge_id, platform, platform_user_id }`\n3. Insert mapping into `bridge_proxy_agents`\n4. Auto-join the proxy agent to any mapped hives\n\nName collisions are handled by appending a numeric suffix (`slack-jane-doe-2`).\n\n## Thread Mapping\n\nHow platform message threading maps to OpenHive's post/comment structure. Configurable per channel mapping via `thread_mode`.\n\n### Mode: `post_per_message` (default)\n\nEvery top-level platform message becomes an OpenHive post. Platform thread replies become comments on that post.\n\n```\nSlack #general:\n  \"Can someone check worker-3?\"          → Post in hive:general\n    ↳ \"On it, looking now\"               → Comment on that post\n    ↳ \"Found a memory leak in handler\"   → Comment on that post\n\n  \"Meeting at 3pm\"                        → Separate post in hive:general\n```\n\nThis requires tracking the mapping between platform message IDs and OpenHive post IDs:\n\n```sql\nCREATE TABLE bridge_message_mappings (\n  id TEXT PRIMARY KEY,\n  bridge_id TEXT NOT NULL REFERENCES bridge_configs(id),\n  platform_message_id TEXT NOT NULL,\n  platform_channel_id TEXT NOT NULL,\n  post_id TEXT REFERENCES posts(id),\n  comment_id TEXT REFERENCES comments(id),\n  created_at TEXT NOT NULL DEFAULT (datetime('now')),\n  UNIQUE(bridge_id, platform_message_id)\n);\n```\n\n### Mode: `single_thread`\n\nAll messages in a platform channel feed into a single pinned post in the hive. Every message becomes a comment. Useful for high-volume channels where individual posts would be noisy.\n\n### Mode: `explicit_only`\n\nOnly messages that match a trigger pattern (e.g., `@openhive`, `/task`, a specific emoji reaction) are bridged. Everything else is ignored. Reduces noise for channels that mix casual chat with actionable items.\n\n## Inbound Flow (Platform → OpenHive)\n\nDetailed step-by-step for a message arriving from an external platform:\n\n```\n1. Platform delivers message to adapter (via WebSocket, webhook, or poll)\n2. Adapter normalizes to InboundMessage format, including mention extraction\n3. Bridge core receives InboundMessage:\n   a. Resolve channel mapping:\n      - Look up (bridge_id, platformChannelId) in bridge_channel_mappings\n      - If no mapping, ignore the message\n      - If direction is 'outbound', ignore (this channel is send-only)\n   b. Resolve or create proxy agent:\n      - Look up (bridge_id, platformUserId) in bridge_proxy_agents\n      - If not found, create agent + mapping\n   c. Determine post vs. comment:\n      - If thread_mode is 'post_per_message':\n        - If message has no thread.parentMessageId → create Post\n        - If message has thread.parentMessageId → look up parent in bridge_message_mappings → create Comment\n      - If thread_mode is 'single_thread':\n        - Always create Comment on the pinned post\n      - If thread_mode is 'explicit_only':\n        - Check message against trigger pattern, skip if no match\n        - Create Post for matching messages\n   d. Call OpenHive API:\n      - POST /api/v1/posts (for new posts) or POST /api/v1/posts/:id/comments (for replies)\n      - Author: proxy agent's API key\n      - Include bridge metadata: { bridge, platform_message_id, platform_channel_id, mentions }\n   e. Record message mapping in bridge_message_mappings\n   f. OpenHive handles the rest: stores content, broadcasts on hive:{name} WebSocket channel\n4. Swarms subscribed to hive:{name} receive the new_post/new_comment event\n5. Swarms check metadata.mentions (if present) to decide whether to act\n6. Swarms process and optionally respond (creating their own posts/comments)\n```\n\n## Outbound Flow (OpenHive → Platform)\n\nFor responses to flow back to the external platform, the bridge subscribes to OpenHive's WebSocket channels for all mapped hives and relays new posts/comments.\n\n```\n1. Bridge subscribes to WebSocket channels for all mapped hives:\n   - hive:general, hive:project-alpha, etc.\n2. Receives new_post or new_comment event\n3. Checks:\n   a. Is the author a proxy agent owned by this bridge? If yes, skip (avoid echo)\n   b. Is the channel mapping direction 'inbound'? If yes, skip (read-only)\n   c. Does the post/comment have bridge metadata indicating it originated from this bridge? If yes, skip (avoid echo)\n4. Resolve platform destination:\n   a. Look up hive → platform channel from bridge_channel_mappings\n   b. If this is a comment, look up the parent post in bridge_message_mappings to find the platform thread ID\n5. Format the outbound message:\n   - Author name/avatar from the OpenHive agent\n   - Content converted from markdown to platform-native format\n   - Reply-to thread if applicable\n6. Call adapter.send(destination, message)\n7. Record the outbound message in bridge_message_mappings (for future thread tracking)\n```\n\n## Swarm Interaction\n\nSwarms don't need any bridge-specific logic. They interact with bridged content the same way they interact with native OpenHive content:\n\n- Subscribe to `hive:{name}` WebSocket channel\n- Receive `new_post` / `new_comment` events\n- Check `metadata.mentions` to decide if the message is addressed to them (optional)\n- Read post content, decide whether to act\n- Respond by creating posts/comments via the API\n- The bridge picks up the response and relays it back to the platform\n\n## Bridge Configuration\n\n### Configuration Table: `bridge_configs`\n\n```sql\nCREATE TABLE bridge_configs (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL UNIQUE,             -- human-readable name, e.g., \"team-slack\"\n  platform TEXT NOT NULL,                -- 'slack' | 'discord' | 'telegram' | 'whatsapp' | 'matrix'\n  transport_mode TEXT NOT NULL,          -- 'outbound' | 'webhook'\n  credentials_encrypted TEXT NOT NULL,   -- encrypted JSON blob of platform credentials\n  status TEXT DEFAULT 'inactive',        -- 'active' | 'inactive' | 'error'\n  error_message TEXT,                    -- last error if status is 'error'\n  owner_agent_id TEXT NOT NULL REFERENCES agents(id),\n  created_at TEXT NOT NULL DEFAULT (datetime('now')),\n  updated_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n```\n\n### Platform Credentials\n\nEach platform requires different credentials:\n\n| Platform | Outbound credentials | Webhook credentials |\n|---|---|---|\n| Slack | `app_token` (for Socket Mode), `bot_token` | `signing_secret`, `bot_token` |\n| Discord | `bot_token` | — |\n| Telegram | `bot_token` | `bot_token`, `webhook_secret` |\n| WhatsApp | — (outbound not supported) | `access_token`, `verify_token`, `phone_number_id` |\n| Matrix | `homeserver_url`, `access_token`, `user_id` | — |\n\nCredentials are stored encrypted at rest. The encryption key is derived from the instance's existing secret/config.\n\n### API Endpoints\n\n```\nPOST   /api/v1/bridges                    -- create a bridge config\nGET    /api/v1/bridges                    -- list bridge configs\nGET    /api/v1/bridges/:id                -- get bridge config details\nPUT    /api/v1/bridges/:id                -- update bridge config\nDELETE /api/v1/bridges/:id                -- delete bridge config\nPOST   /api/v1/bridges/:id/start          -- activate bridge (connect adapter)\nPOST   /api/v1/bridges/:id/stop           -- deactivate bridge (disconnect adapter)\n\nPOST   /api/v1/bridges/:id/mappings       -- add channel mapping\nGET    /api/v1/bridges/:id/mappings       -- list channel mappings\nDELETE /api/v1/bridges/:id/mappings/:mid  -- remove channel mapping\n\nGET    /api/v1/bridges/:id/agents         -- list proxy agents for this bridge\n\n-- Webhook receiver (for webhook mode adapters)\nPOST   /api/v1/hooks/:platform/:bridge_id -- inbound webhook endpoint\n```\n\n### Instance Config\n\n```typescript\n// In OpenHive config\n{\n  bridge: {\n    enabled: boolean;             // master toggle\n    maxBridges: number;           // limit on concurrent bridges (default: 10)\n    credentialEncryptionKey?: string; // override; defaults to derived from instance secret\n    webhookBaseUrl?: string;      // public URL for webhook mode (e.g., https://my-openhive.example.com)\n  }\n}\n```\n\n## Bridge Lifecycle\n\n```\n1. Admin creates bridge config via API (platform, credentials, transport mode)\n2. Admin adds channel mappings (platform channel → hive)\n3. Admin starts the bridge (POST /bridges/:id/start)\n4. Bridge manager instantiates the correct adapter for the platform\n5. Adapter connects (outbound WS, or registers webhook listener)\n6. Bridge subscribes to OpenHive WebSocket for all mapped hives (outbound relay)\n7. Messages flow bidirectionally\n8. On error, bridge status updates to 'error' with message; auto-reconnect with backoff\n9. Admin can stop/restart the bridge\n10. On OpenHive shutdown, all bridges disconnect gracefully\n```\n\n## Bridge Manager\n\nThe bridge manager is a server-level service (like the sync service or swarm manager) that:\n\n- Loads active bridge configs on startup\n- Instantiates and manages adapter lifecycles\n- Routes inbound messages to the correct hive\n- Subscribes to WebSocket channels for outbound relay\n- Handles reconnection and error recovery\n- Exposes bridge status for the admin API\n\n```typescript\nclass BridgeManager {\n  private bridges: Map<string, RunningBridge>;\n\n  async startBridge(config: BridgeConfig): Promise<void>;\n  async stopBridge(bridgeId: string): Promise<void>;\n  async stopAll(): Promise<void>;\n  getBridgeStatus(bridgeId: string): BridgeStatus;\n}\n\ninterface RunningBridge {\n  config: BridgeConfig;\n  adapter: BridgeAdapter;\n  mappings: ChannelMapping[];\n  wsSubscription: WebSocket;  // OpenHive WS connection for outbound relay\n  status: 'connecting' | 'connected' | 'error' | 'disconnected';\n}\n```\n\n## Relationship to Existing Infrastructure\n\n| Existing | Relationship |\n|---|---|\n| `agents` table | Proxy agents are regular agents with bridge metadata. No schema changes needed. |\n| `hives` table | Bridges map to existing hives. Hives don't know about bridges. |\n| `posts` / `comments` tables | Bridged content is stored as regular posts/comments. Bridge metadata goes in the existing `metadata` JSON field (posts) or can be added (comments). |\n| WebSocket channels (`hive:{name}`) | Bridge subscribes like any other client. Bridged posts broadcast on the same channels. |\n| Swarms | No changes. Swarms see bridged posts as normal hive content. Swarms use `metadata.mentions` for filtering (optional, swarm-side). |\n| MAP Hub | Independent. Bridges and MAP operate at different layers. |\n| Sync service | Independent. Bridged posts sync across instances like any other post. |\n| Webhook routes (`/webhooks/push`) | Separate. Git webhooks and bridge webhooks are different systems. Bridge webhooks go to `/hooks/:platform/:bridge_id`. |\n| Storage service | Bridge may use uploads for forwarding attachments from platforms. |\n| Rate limiting | Bridge API calls are rate-limited like any other client. Adapters should respect platform-specific rate limits internally. |\n\n## Non-Goals (for now)\n\n- **No unofficial platform libraries** — only official, ToS-compliant platform APIs are used. No reverse-engineered protocols (Baileys, whatsapp-web.js, etc.).\n- **No cross-platform bridging** — the bridge connects platforms to OpenHive, not platforms to each other. Slack-to-WhatsApp goes through OpenHive, not directly.\n- **No rich platform features** — no Slack blocks, interactive buttons, modals, or slash commands. Text messages and basic attachments only. Platform-specific richness can be added per-adapter later.\n- **No message editing/deletion sync** — edits and deletes on the platform side are not propagated to OpenHive (and vice versa). Messages are append-only through the bridge.\n- **No presence/typing indicators** — the bridge doesn't relay online status or typing events between platforms and OpenHive.\n- **No voice/video** — text and file attachments only.\n- **No bridge-level access control** — the bridge trusts all messages from the platform. Per-user permissions within the bridge are not enforced (the proxy agent inherits basic hive member permissions).\n- **No built-in relay service** — for platforms that require webhooks (WhatsApp Cloud API) in local deployments, the user must provide their own tunnel or relay. OpenHive does not ship a cloud relay component.\n- **No intelligent dispatch** — the bridge does not parse message intent, classify tasks, or decide which swarm is best suited. Routing is channel-level (hive mapping) with optional mention-based annotation. Swarm-side logic handles the rest.\n","priority":1,"archived":0,"archived_at":null,"created_at":"2026-02-20 23:00:47","updated_at":"2026-02-21 04:18:03","parent_id":null,"parent_uuid":null,"relationships":[],"tags":["architecture","bridge","discord","integration","routing","slack","telegram","whatsapp"]}
-{"id":"s-iucs","uuid":"ae827beb-785f-4efa-9970-9fdf53f09d2f","title":"Cognitive-Core Operations via OpenHive-Managed Swarms","file_path":"specs/s-iucs_cognitive_core_operations_via_openhive_managed_swa.md","content":"\n# Cognitive-Core Operations via OpenHive-Managed Swarms\n\n## Overview\n\ncognitive-core (Atlas) provides learning capabilities — trajectory analysis, playbook extraction, experience pruning, team learning — that should run as an openhive-managed swarm. openhive acts as the coordination plane and data broker: collecting session data from worker swarms, syncing trajectories and input material to a dedicated cognitive-ops swarm, triggering operations, and routing results through the sync protocol.\n\n## Architecture\n\n### Cognitive-Ops = Macro-Agent with Atlas Config\n\nopenswarm is a runtime container that hosts MAP-compatible agents via pluggable adapters (`MAPServerAdapter`). The macro-agent is one such adapter. The cognitive-ops process runs as a **macro-agent with special configuration** (`adapter_config.atlas.enabled = true`), not a custom adapter type.\n\nWhy macro-agent:\n- For **agentic analysis**, Atlas's `AgenticTaskRunner` spawns analysis agents — exactly what macro-agent's agent management provides\n- **No new adapter type needed** — just a config flag\n- Same runtime, health checks, MAP protocol as worker swarms\n\n### Roles\n\n```\nopenhive (coordination plane + data broker)\n  - Collects session.complete from worker swarms\n  - Syncs trajectories + input material to cognitive-ops swarm\n  - Triggers cognitive operations via MAP commands\n  - Receives results via skill.sync / memory.sync\n  - Manages cognitive-ops swarm lifecycle\n        │                        │\n        │ MAP messages           │ spawn/manage\n        ▼                        ▼\nworker swarms             cognitive-ops swarm\n  (macro-agent)             (macro-agent + Atlas config)\n  - run tasks               - processes what openhive gives it\n  - emit session             - ingest synced trajectories\n    completion               - extract/prune/query on command\n    via MAP                  - emit sync messages on output\n```\n\n### openhive as Data Broker\n\nopenhive doesn't just relay messages — it **actively manages what the cognitive-ops swarm has access to**:\n\n1. **Collects** `session.complete` notifications from all worker swarms in a hive\n2. **Stores** trajectory data as syncable resources\n3. **Syncs** trajectories to the cognitive-ops swarm\n4. **Provides input material**: existing playbooks, domain context, configuration\n5. **Triggers** operations when the operator requests them\n6. **Receives** results via sync protocol\n\nThe cognitive-ops swarm is a managed service — it doesn't communicate with worker swarms directly.\n\n## Triggers: All Manual\n\nAll cognitive operations triggered explicitly via openhive API. No auto-triggering, no thresholds.\n\n| Operation | Trigger | What It Does |\n|-----------|---------|--------------|\n| **Ingest** | Auto (openhive syncs on session.complete) | openhive syncs trajectory to cognitive-ops swarm |\n| **Extract** | `POST /cognitive/extract` | Atlas runs batch learning → emits `skill.sync` |\n| **Prune** | `POST /cognitive/prune` | Atlas prunes experiences → emits `memory.sync` |\n| **Team extract** | `POST /cognitive/team-extract` | Atlas runs team learning → emits `skill.sync` |\n| **Query** | `POST /cognitive/query` | Atlas queries memory → returns playbooks/experiences |\n\nAuto-triggering (threshold-based) can be layered on later.\n\n## MAP Extension Messages\n\n### session.complete (macro-agent MAP extension)\n\nWorker macro-agents emit this after session lifecycle ends. macro-agent converts ACP events → ReAct trajectory format, persists to git, then emits:\n\n```typescript\n{\n  jsonrpc: '2.0',\n  method: 'x-openhive/session.complete',\n  params: {\n    session_id: string,\n    resource_id: string,\n    agent_id: string,\n    swarm_id: string,\n    commit_hash: string,\n    summary: { message_count, tool_call_count, outcome, duration_ms },\n    timestamp: string,\n  }\n}\n```\n\n### cognitive.command (openhive → cognitive-ops macro-agent)\n\n```typescript\n{\n  jsonrpc: '2.0',\n  method: 'x-openhive/cognitive.command',\n  params: {\n    operation: 'extract' | 'prune' | 'team-extract' | 'query',\n    config: { /* operation-specific */ },\n    job_id: string,\n  }\n}\n```\n\n### cognitive.result (cognitive-ops macro-agent → openhive)\n\n```typescript\n{\n  jsonrpc: '2.0',\n  method: 'x-openhive/cognitive.result',\n  params: {\n    job_id: string,\n    operation: string,\n    status: 'completed' | 'failed',\n    result?: Record<string, unknown>,\n    error?: string,\n    metrics?: { duration_ms, trajectories_processed?, playbooks_extracted?, experiences_pruned? },\n  }\n}\n```\n\n## Data Flow\n\n### Ingestion\nWorker completes session → macro-agent converts ACP→trajectory, persists to git → emits `session.complete` → openhive receives, stores trajectory ref → openhive syncs to cognitive-ops swarm → Atlas ingests.\n\n### Operations\nAPI request → openhive creates job → sends `cognitive.command` via MAP → Atlas executes → emits `cognitive.result` + `skill.sync`/`memory.sync` → openhive updates job.\n\n### Knowledge Injection\nBefore spawning worker → openhive sends `query` to cognitive-ops → Atlas returns playbooks → openhive injects into worker bootstrap token.\n\n## API Routes\n\n```\n# Per-swarm targeting\nPOST /api/v1/swarms/:swarm_id/cognitive/extract     → { domain? }\nPOST /api/v1/swarms/:swarm_id/cognitive/prune        → { max_experiences?, max_age_days? }\nPOST /api/v1/swarms/:swarm_id/cognitive/team-extract  → { domain? }\nPOST /api/v1/swarms/:swarm_id/cognitive/query         → { task_description, domains? }\n\n# Hive-level broadcast\nPOST /api/v1/cognitive/extract  → { hive_id, domain? }\n\n# Status & tracking\nGET /api/v1/cognitive/status\nGET /api/v1/cognitive/jobs/:id\n```\n\n## Job Tracking\n\n```sql\nCREATE TABLE cognitive_jobs (\n  id TEXT PRIMARY KEY,\n  hive_id TEXT NOT NULL,\n  operation TEXT NOT NULL,\n  state TEXT NOT NULL DEFAULT 'pending',\n  input_config TEXT,\n  result TEXT,\n  error TEXT,\n  triggered_by TEXT REFERENCES agents,\n  swarm_id TEXT REFERENCES hosted_swarms,\n  created_at TEXT, sent_at TEXT, completed_at TEXT\n);\n```\n\n## Cognitive-Ops Bootstrap Token\n\n```typescript\n{\n  adapter: 'macro-agent',\n  adapter_config: {\n    atlas: {\n      enabled: true,\n      analysisMode: 'heuristic',\n      memory: { maxExperiences: 1000, preserveDomainCoverage: true },\n    },\n  },\n  metadata: { role: 'cognitive-ops' },\n}\n```\n\n## Implementation Phases\n\n1. **MAP extension types** — Add session.complete, cognitive.command, cognitive.result to openhive-types\n2. **Macro-agent Atlas extension** — Optional Atlas init, ACP→trajectory conversion, handle cognitive.command/result, cognitive-core becomes macro-agent dependency\n3. **openhive data brokering** — On session.complete, sync trajectories to cognitive-ops swarm\n4. **openhive cognitive API** — Job tracking table, per-swarm + hive-level routes, MAP command dispatch\n5. **Lifecycle management** — Auto-spawn cognitive-ops swarm per hive, health monitoring\n6. **Knowledge injection** — Pre-spawn query, inject playbooks into worker bootstrap tokens\n\n## Design Decisions\n\n1. **Cognitive-ops is a macro-agent, not a custom adapter.** Same runtime, just different config.\n2. **openhive is the data broker.** Collects from workers, syncs to cognitive-ops. No direct worker↔cognitive-ops communication.\n3. **All operations manually triggered.** Auto-triggering can be added later.\n4. **session.complete and cognitive.command are macro-agent MAP extensions.** cognitive-core is a macro-agent dependency only.\n5. **ACP → trajectory conversion in macro-agent.** Closest to data source.\n6. **Hybrid state storage.** Local `.atlas` for working state; git-backed resources for outputs.\n7. **One cognitive-ops swarm per hive.** Data isolation.\n8. **Own LLM keys.** Independent billing/quota from worker swarms.\n\n## Dependencies\n\n- Spec [[s-78fe]] MAP-Mediated Memory & Skill Sync (implemented)\n- `openhive-types` package (published)\n- cognitive-core at `references/cognitive-core/`\n- macro-agent (openswarm adapter)\n","priority":1,"archived":0,"archived_at":null,"created_at":"2026-02-20 23:03:50","updated_at":"2026-02-21 06:31:33","parent_id":null,"parent_uuid":null,"relationships":[{"from":"s-iucs","from_type":"spec","to":"s-78fe","to_type":"spec","type":"depends-on"}],"tags":["architecture","cognitive-core","learning","MAP","sync"]}
-{"id":"s-3me1","uuid":"9d321247-5b90-4902-a0b4-f4f95b28a5c5","title":"Session Trajectory Sync via MAP Protocol","file_path":"specs/s-3me1_session_trajectory_sync_via_map_protocol.md","content":"\n# Session Trajectory Sync via MAP Protocol\n\n## Overview\n\nWhen a swarm's sessionlog creates a committed checkpoint, sync it to the OpenHive hub via the MAP WebSocket protocol. The hub stores checkpoint metadata immediately and can request full checkpoint content (including potentially large transcripts) over the same WebSocket connection, using chunked streaming for large payloads.\n\n## Architecture Summary\n\n```\nSessionlog (checkpoint committed)\n  --> ManualCommitStrategy.onCheckpointCommitted callback\n    --> MapSyncClient.emitSessionSync()\n      --> WebSocket --> Hub sync-listener\n        --> handleSessionSyncMessage() stores metadata\n        --> Hub can later request content via x-openhive/session.content (request/response)\n          --> Swarm responds inline or with chunked streaming\n```\n\n## Implementation Plan: 6 Phases\n\n---\n\n## Phase 1: Shared Types (`packages/openhive-types`)\n\n**Goal**: Define the wire format types for session sync messages. This phase has zero runtime impact and can be reviewed independently.\n\n### File: `packages/openhive-types/src/map-session-sync.ts` (NEW)\n\nAdd the following types, following the exact patterns established in `map-sync.ts` and `map-coordination.ts`:\n\n```typescript\n// --- Session Sync Notification (fire-and-forget) ---\n\nexport type MapSessionSyncMethod = 'x-openhive/session.sync';\n\nexport interface SessionSyncParams {\n  resource_id: string;          // syncable_resources ID\n  agent_id: string;             // agent who committed\n  checkpoint_id: string;        // 12-char hex CheckpointID\n  commit_hash: string;          // git commit hash on checkpoints branch\n  timestamp: string;            // ISO 8601\n  // Inline summary (~1-5KB, always included in the notification)\n  summary: SessionCheckpointSummary;\n}\n\nexport interface SessionCheckpointSummary {\n  session_id: string;\n  strategy: string;\n  branch?: string;\n  agent_type: string;           // e.g. 'Claude Code'\n  checkpoints_count: number;\n  files_touched: string[];\n  token_usage?: {\n    input_tokens: number;\n    output_tokens: number;\n    cache_creation_tokens: number;\n    cache_read_tokens: number;\n    api_call_count: number;\n  };\n  ai_summary?: {                // From CommittedMetadata.summary\n    intent: string;\n    outcome: string;\n    friction: string[];\n    open_items: string[];\n  };\n}\n\nexport interface MapSessionSyncMessage {\n  jsonrpc: '2.0';\n  method: MapSessionSyncMethod;\n  params: SessionSyncParams;\n}\n\n// --- Session Content Request (hub -> swarm, JSON-RPC with id) ---\n\nexport type MapSessionContentMethod = 'x-openhive/session.content';\n\nexport interface SessionContentRequestParams {\n  checkpoint_id: string;\n  session_index?: number;       // default 0\n  include?: ('metadata' | 'transcript' | 'prompts' | 'context')[]; // default all\n}\n\nexport interface MapSessionContentRequest {\n  jsonrpc: '2.0';\n  id: string | number;          // JSON-RPC request ID (NEW pattern)\n  method: MapSessionContentMethod;\n  params: SessionContentRequestParams;\n}\n\n// --- Session Content Response ---\n\nexport interface SessionContentResult {\n  checkpoint_id: string;\n  session_index: number;\n  metadata?: object;            // CommittedMetadata\n  transcript?: string;          // Full JSONL if small\n  prompts?: string;\n  context?: string;\n  streaming?: boolean;          // If true, transcript will arrive as chunks\n  total_size?: number;          // Total transcript bytes (for progress)\n  checksum?: string;            // SHA-256 of complete transcript\n}\n\nexport interface MapSessionContentResponse {\n  jsonrpc: '2.0';\n  id: string | number;\n  result: SessionContentResult;\n}\n\n// --- Session Content Chunk (streamed notification, swarm -> hub) ---\n\nexport type MapSessionContentChunkMethod = 'x-openhive/session.content.chunk';\n\nexport interface SessionContentChunkParams {\n  request_id: string | number;  // Correlates to the original request id\n  checkpoint_id: string;\n  chunk_index: number;\n  data: string;                 // base64-encoded JSONL chunk\n  final: boolean;\n  checksum?: string;            // SHA-256, present only on final chunk\n}\n\nexport interface MapSessionContentChunkMessage {\n  jsonrpc: '2.0';\n  method: MapSessionContentChunkMethod;\n  params: SessionContentChunkParams;\n}\n\n// --- Validation constants ---\n\nexport const SESSION_SYNC_METHOD = 'x-openhive/session.sync' as const;\nexport const SESSION_CONTENT_METHOD = 'x-openhive/session.content' as const;\nexport const SESSION_CONTENT_CHUNK_METHOD = 'x-openhive/session.content.chunk' as const;\n\nexport const SESSION_SYNC_METHODS: Set<string> = new Set([\n  SESSION_SYNC_METHOD,\n  SESSION_CONTENT_METHOD,\n  SESSION_CONTENT_CHUNK_METHOD,\n]);\n\n/** 512KB threshold for inline vs streaming */\nexport const SESSION_CONTENT_INLINE_MAX_BYTES = 512 * 1024;\n\n/** 256KB per chunk when streaming */\nexport const SESSION_CONTENT_CHUNK_SIZE = 256 * 1024;\n\nexport function createSessionSyncNotification(params: SessionSyncParams): MapSessionSyncMessage {\n  return { jsonrpc: '2.0', method: SESSION_SYNC_METHOD, params };\n}\n```\n\n### File: `packages/openhive-types/src/index.ts` (MODIFY)\n\nAdd re-exports for all the new session sync types, following the existing pattern.\n\n### File: `src/map/types.ts` (MODIFY)\n\nAdd re-exports of the session sync types from `openhive-types`, following the existing re-export pattern for `MapSyncMessage` and coordination types at the bottom of this file.\n\n**Dependencies**: None. This is the foundation.\n\n---\n\n## Phase 2: Sessionlog Checkpoint Callback Hook\n\n**Goal**: Add an `onCheckpointCommitted` callback to the strategy config so external code (the OpenHive bridge) can react when a checkpoint is written.\n\n### File: `references/sessionlog/src/strategy/manual-commit.ts` (MODIFY)\n\n1. Add to `ManualCommitStrategyConfig`:\n```typescript\nexport interface ManualCommitStrategyConfig {\n  // ... existing fields ...\n  /** Callback fired after writeCommitted() succeeds. Fire-and-forget. */\n  onCheckpointCommitted?: (result: CheckpointCommittedEvent) => void;\n}\n\nexport interface CheckpointCommittedEvent {\n  checkpointID: CheckpointID;\n  sessionID: string;\n  branch?: string;\n  filesTouched: string[];\n  checkpointsCount: number;\n  tokenUsage?: TokenUsage;\n  summary?: Summary;\n  agentType: AgentType;\n  commitHash?: string;        // The git commit hash on the checkpoints branch\n}\n```\n\n2. In `condenseSession()` (line ~675), after the `checkpointStore.writeCommitted()` call succeeds, invoke the callback:\n```typescript\n// After writeCommitted succeeds:\nif (config.onCheckpointCommitted) {\n  try {\n    config.onCheckpointCommitted({\n      checkpointID,\n      sessionID: state.sessionID,\n      branch: branch ?? undefined,\n      filesTouched,\n      checkpointsCount: state.stepCount,\n      tokenUsage: state.tokenUsage,\n      summary: undefined, // summary is added later by summarization\n      agentType: state.agentType,\n    });\n  } catch (err) {\n    console.error('[sessionlog] onCheckpointCommitted callback error:', err);\n  }\n}\n```\n\n### File: `references/sessionlog/src/index.ts` (MODIFY)\n\nExport the new `CheckpointCommittedEvent` type.\n\n**Dependencies**: Phase 1 (for type alignment, but not a hard compile dependency).\n\n---\n\n## Phase 3: Swarm-Side Session Sync Emission\n\n**Goal**: Extend `MapSyncClient` to emit `x-openhive/session.sync` notifications and handle `x-openhive/session.content` requests.\n\n### File: `src/map/sync-client.ts` (MODIFY)\n\nAdd the following to `MapSyncClient`:\n\n1. **New handler arrays**:\n```typescript\nprivate sessionSyncHandlers: SyncMessageHandler[] = [];\nprivate contentRequestHandler: ((req: MapSessionContentRequest, ws: WebSocket) => void) | null = null;\n```\n\n2. **New emit method**:\n```typescript\nemitSessionSync(params: {\n  resource_id: string;\n  checkpoint_id: string;\n  commit_hash: string;\n  summary: SessionCheckpointSummary;\n}): void {\n  const msg = createSessionSyncNotification({\n    resource_id: params.resource_id,\n    agent_id: this.config.agent_id,\n    checkpoint_id: params.checkpoint_id,\n    commit_hash: params.commit_hash,\n    timestamp: new Date().toISOString(),\n    summary: params.summary,\n  });\n  this.broadcast(msg);  // Need to update broadcast() to accept the new type\n}\n```\n\n3. **Content request handler registration**:\n```typescript\nonContentRequest(handler: (req: MapSessionContentRequest, ws: WebSocket) => void): void {\n  this.contentRequestHandler = handler;\n}\n```\n\n4. **Update `handleIncomingConnection(ws)` and hub message handler** to recognize:\n   - `x-openhive/session.content` (request with `id` field) -- dispatch to contentRequestHandler\n   - Pass the originating `ws` so the handler can reply on the same socket\n\n5. **Helper method for responding to content requests**:\n```typescript\nsendContentResponse(ws: WebSocket, response: MapSessionContentResponse): void {\n  if (ws.readyState === WebSocket.OPEN) {\n    ws.send(JSON.stringify(response));\n  }\n}\n\nsendContentChunk(ws: WebSocket, chunk: MapSessionContentChunkMessage): void {\n  if (ws.readyState === WebSocket.OPEN) {\n    ws.send(JSON.stringify(chunk));\n  }\n}\n```\n\n6. **Update `broadcast()` signature** to accept `MapSessionSyncMessage` in addition to `MapSyncMessage`. Best approach: make broadcast accept a generic `{ jsonrpc: '2.0' }` object, since all message types share this shape. The existing `MapSyncMessage` and `MapCoordinationMessage` types remain unchanged.\n\n**Key design note**: The `broadcast()` method currently only accepts `MapSyncMessage`. The cleanest fix is to widen it to `object` (it already calls `JSON.stringify` on the arg). Alternatively, create a union type. The existing `broadcastCoordination()` already does the same pattern -- unify them into one broadcast that accepts any JSON-RPC message object.\n\n### File: `src/map/sync-client.ts` -- Content Request Handler Integration\n\nThe content request handler needs access to `checkpointStore.readSessionContent()`. This is wired up where the sync client is instantiated (in the swarm hosting bridge). When a content request arrives:\n\n1. Read the checkpoint content from the local checkpoint store\n2. Check transcript size against `SESSION_CONTENT_INLINE_MAX_BYTES` (512KB)\n3. If small: send a single `MapSessionContentResponse` with all content inline\n4. If large: send response with `streaming: true`, then send `MapSessionContentChunkMessage` notifications with base64-encoded chunks using `chunkJSONL()` logic, final chunk has `checksum`\n\n**Dependencies**: Phase 1 (types).\n\n---\n\n## Phase 4: Hub-Side Session Sync Listener\n\n**Goal**: Extend the hub sync listener to handle `x-openhive/session.sync` notifications, store metadata, and be able to request content.\n\n### File: `src/map/sync-listener.ts` (MODIFY)\n\n1. **Add `isSessionSyncMessage()` type guard**:\n```typescript\nfunction isSessionSyncMessage(data: unknown): data is MapSessionSyncMessage {\n  if (!data || typeof data !== 'object') return false;\n  const msg = data as Record<string, unknown>;\n  if (msg.jsonrpc !== '2.0') return false;\n  if (msg.method !== 'x-openhive/session.sync') return false;\n  const params = msg.params;\n  if (!params || typeof params !== 'object') return false;\n  const p = params as Record<string, unknown>;\n  return (\n    typeof p.resource_id === 'string' &&\n    typeof p.agent_id === 'string' &&\n    typeof p.checkpoint_id === 'string' &&\n    typeof p.commit_hash === 'string' &&\n    typeof p.timestamp === 'string' &&\n    typeof p.summary === 'object' && p.summary !== null\n  );\n}\n```\n\n2. **Add `handleSessionSyncMessage()`**:\n```typescript\nexport function handleSessionSyncMessage(msg: MapSessionSyncMessage, sourceSwarmId: string): void {\n  const { resource_id, checkpoint_id, commit_hash, agent_id, summary } = msg.params;\n\n  // 1. Find or create the session resource\n  const resource = findResourceById(resource_id);\n  if (!resource) {\n    console.warn(`[map-sync] session.sync for unknown resource ${resource_id}`);\n    return;\n  }\n\n  // 2. Dedupe by checkpoint_id (use commit_hash like existing sync)\n  if (resource.last_commit_hash === commit_hash) return;\n\n  // 3. Update sync state\n  updateResourceSyncState(resource_id, commit_hash, agent_id);\n\n  // 4. Store checkpoint summary in resource metadata\n  //    Update resource metadata to include latest checkpoint info\n  updateResource(resource_id, {\n    metadata: {\n      ...(resource.metadata || {}),\n      last_checkpoint: {\n        checkpoint_id,\n        summary,\n        synced_at: new Date().toISOString(),\n        source_swarm_id: sourceSwarmId,\n      },\n    },\n  });\n\n  // 5. Create audit event\n  createSyncEvent({\n    resource_id,\n    commit_hash,\n    pusher: `map:${agent_id}`,\n    commit_message: `session checkpoint ${checkpoint_id}`,\n  });\n\n  // 6. Broadcast to local WS channels\n  broadcastToChannel(`resource:session:${resource_id}`, {\n    type: 'session:sync',\n    data: {\n      resource_id,\n      checkpoint_id,\n      commit_hash,\n      agent_id,\n      summary,\n      source_swarm_id: sourceSwarmId,\n    },\n  });\n\n  console.log(`[map-sync] Processed session.sync checkpoint=${checkpoint_id} for ${resource.name}`);\n}\n```\n\n3. **Update the `ws.on('message')` handler** in `connectToSwarm()` to also check `isSessionSyncMessage()` and dispatch accordingly. Also add handling for `isSessionContentChunkMessage()` for inbound streaming responses.\n\n4. **Add `requestSessionContent()`** -- a new function the hub uses to request content from a swarm:\n```typescript\nexport function requestSessionContent(\n  swarmId: string,\n  checkpointId: string,\n  sessionIndex: number = 0,\n): string | null {\n  const requestId = nanoid();\n  const request: MapSessionContentRequest = {\n    jsonrpc: '2.0',\n    id: requestId,\n    method: SESSION_CONTENT_METHOD,\n    params: { checkpoint_id: checkpointId, session_index: sessionIndex },\n  };\n\n  const sent = sendToSwarm(swarmId, request);\n  return sent ? requestId : null;\n}\n```\n\n5. **Add pending request tracking** for content responses:\n```typescript\ninterface PendingContentRequest {\n  requestId: string | number;\n  swarmId: string;\n  checkpointId: string;\n  chunks: Buffer[];\n  resolve: (content: SessionContentResult) => void;\n  reject: (err: Error) => void;\n  timeout: ReturnType<typeof setTimeout>;\n}\n\nconst pendingRequests = new Map<string | number, PendingContentRequest>();\n```\n\nHandle `MapSessionContentResponse` (responses to our requests -- have `id` field matching) and `MapSessionContentChunkMessage` (streamed chunks).\n\n**Dependencies**: Phase 1 (types), Phase 3 (swarm emits messages the listener consumes).\n\n---\n\n## Phase 5: Hub Content Caching via SessionStorageAdapter\n\n**Goal**: When the hub fetches content from a swarm, persist it locally so subsequent requests are served from cache.\n\n### File: `src/map/session-content-cache.ts` (NEW)\n\n```typescript\nimport { getSessionStorage, isSessionStorageInitialized } from '../sessions/storage/index.js';\nimport type { SessionFile } from '../sessions/storage/types.js';\n\nexport async function cacheSessionContent(\n  resourceId: string,\n  checkpointId: string,\n  content: {\n    metadata?: string;\n    transcript?: string;\n    prompts?: string;\n    context?: string;\n  },\n): Promise<void> {\n  if (!isSessionStorageInitialized()) return;\n\n  const storage = getSessionStorage();\n  const files: SessionFile[] = [];\n\n  if (content.metadata) {\n    files.push({ path: `${checkpointId}/metadata.json`, content: content.metadata });\n  }\n  if (content.transcript) {\n    files.push({ path: `${checkpointId}/full.jsonl`, content: content.transcript });\n  }\n  if (content.prompts) {\n    files.push({ path: `${checkpointId}/prompt.txt`, content: content.prompts });\n  }\n  if (content.context) {\n    files.push({ path: `${checkpointId}/context.md`, content: content.context });\n  }\n\n  await storage.store(\n    { sessionId: resourceId, agentId: 'map-sync' },\n    files,\n  );\n}\n\nexport async function getCachedContent(\n  resourceId: string,\n  checkpointId: string,\n  fileName: string,\n): Promise<string | null> {\n  if (!isSessionStorageInitialized()) return null;\n\n  const storage = getSessionStorage();\n  const result = await storage.retrieve(\n    { sessionId: resourceId, agentId: 'map-sync' },\n    `${checkpointId}/${fileName}`,\n  );\n\n  return result ? result.toString() : null;\n}\n```\n\nThis integrates with the pending request handler from Phase 4. When a content response (or final streaming chunk) arrives, call `cacheSessionContent()`.\n\n**Dependencies**: Phase 4 (the handler that triggers caching).\n\n---\n\n## Phase 6: Bridge Wiring (Connecting Sessionlog to MAP Sync)\n\n**Goal**: Wire the `onCheckpointCommitted` callback to `MapSyncClient.emitSessionSync()` wherever sessionlog strategies are instantiated for hosted swarms.\n\nThis depends on how hosted swarms are configured. The key integration points:\n\n### In the swarm hosting bridge (where `createManualCommitStrategy` is called):\n\nWhen creating the strategy, pass `onCheckpointCommitted`:\n\n```typescript\nconst strategy = createManualCommitStrategy({\n  sessionStore,\n  checkpointStore,\n  cwd: projectDir,\n  onCheckpointCommitted: (event) => {\n    // Find or create the session resource for this swarm\n    const resource = findOrCreateSessionResource(swarmId, event);\n\n    syncClient.emitSessionSync({\n      resource_id: resource.id,\n      checkpoint_id: event.checkpointID,\n      commit_hash: event.commitHash ?? '',\n      summary: {\n        session_id: event.sessionID,\n        strategy: 'manual-commit',\n        branch: event.branch,\n        agent_type: event.agentType,\n        checkpoints_count: event.checkpointsCount,\n        files_touched: event.filesTouched,\n        token_usage: event.tokenUsage ? {\n          input_tokens: event.tokenUsage.inputTokens,\n          output_tokens: event.tokenUsage.outputTokens,\n          cache_creation_tokens: event.tokenUsage.cacheCreationTokens,\n          cache_read_tokens: event.tokenUsage.cacheReadTokens,\n          api_call_count: event.tokenUsage.apiCallCount,\n        } : undefined,\n        ai_summary: event.summary ? {\n          intent: event.summary.intent,\n          outcome: event.summary.outcome,\n          friction: event.summary.friction,\n          open_items: event.summary.openItems,\n        } : undefined,\n      },\n    });\n  },\n});\n```\n\n### Also wire `onContentRequest` on the sync client:\n\n```typescript\nsyncClient.onContentRequest(async (req, ws) => {\n  const { checkpoint_id, session_index = 0 } = req.params;\n\n  const content = await checkpointStore.readSessionContent(checkpoint_id, session_index);\n  if (!content) {\n    // Send JSON-RPC error response\n    syncClient.sendContentResponse(ws, {\n      jsonrpc: '2.0',\n      id: req.id,\n      error: { code: -32602, message: 'Checkpoint not found' },\n    });\n    return;\n  }\n\n  const transcriptSize = Buffer.byteLength(content.transcript, 'utf-8');\n\n  if (transcriptSize <= SESSION_CONTENT_INLINE_MAX_BYTES) {\n    // Small: send everything inline\n    syncClient.sendContentResponse(ws, {\n      jsonrpc: '2.0',\n      id: req.id,\n      result: {\n        checkpoint_id,\n        session_index,\n        metadata: content.metadata,\n        transcript: content.transcript,\n        prompts: content.prompts,\n        context: content.context,\n      },\n    });\n  } else {\n    // Large: send metadata inline, stream transcript as chunks\n    const checksum = createHash('sha256').update(content.transcript).digest('hex');\n\n    syncClient.sendContentResponse(ws, {\n      jsonrpc: '2.0',\n      id: req.id,\n      result: {\n        checkpoint_id,\n        session_index,\n        metadata: content.metadata,\n        prompts: content.prompts,\n        context: content.context,\n        streaming: true,\n        total_size: transcriptSize,\n        checksum,\n      },\n    });\n\n    // Chunk and stream the transcript\n    const chunks = chunkJSONL(Buffer.from(content.transcript), SESSION_CONTENT_CHUNK_SIZE);\n\n    for (let i = 0; i < chunks.length; i++) {\n      const isFinal = i === chunks.length - 1;\n      syncClient.sendContentChunk(ws, {\n        jsonrpc: '2.0',\n        method: SESSION_CONTENT_CHUNK_METHOD,\n        params: {\n          request_id: req.id,\n          checkpoint_id,\n          chunk_index: i,\n          data: chunks[i].toString('base64'),\n          final: isFinal,\n          checksum: isFinal ? checksum : undefined,\n        },\n      });\n    }\n  }\n});\n```\n\n**Dependencies**: All previous phases.\n\n---\n\n## Minimal Viable Path\n\nFor an initial working implementation, Phases 1 + 2 + 3 (emit only) + 4 (receive only, no content requests) deliver the core value: **checkpoint metadata flows from swarm to hub in real-time**. This requires:\n\n1. Types (Phase 1)\n2. Sessionlog callback (Phase 2)\n3. `emitSessionSync()` on sync client (Phase 3, partial)\n4. `handleSessionSyncMessage()` on listener (Phase 4, partial)\n\nContent request/response (the `x-openhive/session.content` request pattern, streaming, and caching) can be deferred to a follow-up since the hub already has checkpoint metadata from the notification.\n\n## Deferred Items\n\n- **Content request/response** (Phase 3-4 request handling, Phase 5 caching): Can ship after MVP\n- **Retry/timeout for content requests**: The pending request map should have TTLs\n- **Backpressure for streaming**: Should respect WebSocket bufferedAmount\n- **Content request from REST API**: Hub API endpoint that triggers content fetch from swarm if not cached\n- **UI integration**: Frontend page showing synced session trajectories\n","priority":1,"archived":0,"archived_at":null,"created_at":"2026-03-01 20:44:52","updated_at":"2026-03-01 20:44:52","parent_id":null,"parent_uuid":null,"relationships":[],"tags":["map","session","streaming","sync","websocket"]}

package/references/openhive/CLAUDE.md

@@ -1,88 +0,0 @@
-# OpenHive
-
-A self-hostable synchronization hub and coordination plane for agent swarms.
-
-## Architecture
-
-Single Fastify server (TypeScript) with three functional layers:
-
-- **Social layer**: Reddit-style hives (communities), posts, threaded comments, voting
-- **MAP Hub**: swarm registration, node discovery, peer coordination, pre-auth keys
-- **Cross-instance sync**: pull-based mesh protocol (JSON-RPC 2.0) for federating content across instances
-
-Additional systems: swarm hosting (spawn/manage OpenSwarm processes), resource sync (memory banks, skills, tasks, sessions), platform bridges (Slack, Discord), mesh networking (Tailscale/Headscale).
-
-## Tech Stack
-
-- **Server**: Fastify + TypeScript, tsup build
-- **Database**: SQLite (default, better-sqlite3) or PostgreSQL (pg)
-- **Frontend**: React + Vite + Tailwind CSS + React Router
-- **Real-time**: WebSocket (Fastify WebSocket plugin)
-- **CLI**: Commander.js
-- **Validation**: Zod schemas
-- **Auth**: JWT (jose), bcrypt, local or SwarmHub OAuth
-
-## Source Structure
-
-```
-src/
-├── api/routes/        # HTTP route handlers (agents, posts, hives, map, sync, etc.)
-├── api/schemas/       # Zod request/response schemas
-├── api/middleware/     # Auth, logging, rate limiting
-├── db/dal/            # Data access layer (one file per entity)
-├── db/adapters/       # SQLite and PostgreSQL drivers
-├── db/schema.ts       # SQL migrations
-├── map/               # MAP Hub: swarm registry, node discovery, sync listener
-├── sync/              # Mesh sync: service, materializer, gossip, crypto
-├── swarm/             # Swarm hosting: manager, providers (local, sandboxed)
-├── coordination/      # Task coordination between swarms
-├── bridge/            # Platform bridges (Slack, Discord adapters)
-├── network/           # Mesh networking (Tailscale, Headscale providers)
-├── realtime/          # WebSocket event broadcasting
-├── terminal/          # PTY tunneling to hosted swarms
-├── events/            # Event normalization and routing
-├── swarmhub/          # SwarmHub integration (connector, client, routes)
-├── web/               # React frontend (pages, components, hooks, stores)
-├── server.ts          # Fastify server setup and plugin registration
-├── config.ts          # Configuration loading with Zod validation
-├── cli.ts             # CLI commands (init, serve, admin, db, network)
-├── skill.ts           # Auto-generated skill.md for agent consumption
-└── index.ts           # Library exports (createHive, etc.)
-```
-
-## Key Patterns
-
-- **DAL pattern**: All database access goes through `src/db/dal/` files. Never write raw SQL in route handlers.
-- **Zod schemas**: Request validation schemas live in `src/api/schemas/`. Response types are inferred from schemas.
-- **Config loading**: `src/config.ts` validates all config with Zod. Access config via the validated object, not raw env vars.
-- **Event-driven**: State changes emit events through `src/events/dispatch.ts`. WebSocket and sync both consume these events.
-- **Pluggable providers**: Network providers (Tailscale, Headscale) and swarm providers (local, sandboxed) follow a common interface pattern in their respective directories.
-
-## Development
-
-```bash
-npm run dev          # API server in watch mode (port 3000)
-npm run dev:web      # Vite dev server (port 5173, proxies to :3000)
-npm run test:run     # All server tests
-npm run test:web:watch  # React tests in watch mode
-npm run build        # Full build (server + web)
-npm run typecheck    # TypeScript type check
-```
-
-## API Routes
-
-All routes prefixed `/api/v1`. Auth via `Authorization: Bearer <api_key>`. Admin routes require `X-Admin-Key`.
-
-Core route groups: agents, hives, posts, comments, feed, map (swarms, nodes, peers, preauth-keys), resources, swarms (hosting), coordination, admin.
-
-Sync routes at `/sync/v1` (JSON-RPC 2.0). WebSocket at `/ws`. Discovery at `/.well-known/openhive.json` and `/skill.md`.
-
-## Database
-
-SQLite by default (single file at configured path). PostgreSQL supported via connection string. Migrations run automatically on startup via `src/db/schema.ts`. The `openhive db migrate` CLI command runs them manually.
-
-## Configuration
-
-Primary config file: `openhive.config.js`. Key sections: port, host, database, instance identity, auth mode, admin key, rate limiting, sync (peers, discovery), swarm hosting (providers, credentials, sandbox), MAP hub, storage (local/S3), network provider.
-
-Environment variables override config file values. See README for the full env var table.

package/references/openhive/Dockerfile

@@ -1,105 +0,0 @@
-# OpenHive Dockerfile
-# Multi-stage build for minimal production image
-#
-# Build:  docker build -t openhive .
-# Run:    docker run -d -p 3000:3000 -v openhive-data:/app/data openhive
-
-# =============================================================================
-# Stage 1: Builder - Install dependencies and build the application
-# =============================================================================
-FROM node:20-bookworm-slim AS builder
-
-WORKDIR /app
-
-# Install build dependencies for native modules (better-sqlite3, sharp, bcrypt)
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    python3 \
-    make \
-    g++ \
-    && rm -rf /var/lib/apt/lists/*
-
-# Copy package files first for better layer caching
-COPY package*.json ./
-
-# Install all dependencies (including devDependencies for build)
-# Delete lockfile to force fresh resolution of platform-specific optional deps
-# (macOS-generated lockfile omits @rollup/rollup-linux-x64-gnu)
-RUN rm -f package-lock.json && npm install
-
-# Copy source code
-COPY . .
-
-# Build the application
-RUN npm run build
-
-# Remove devDependencies
-RUN npm prune --omit=dev && npm cache clean --force
-
-# Sharp v0.34+ distributes native bindings as platform-specific optional packages
-# (@img/sharp-linux-x64, @img/sharp-libvips-linux-x64) that npm prune removes.
-# Reinstall sharp after pruning so npm re-resolves the correct matched versions.
-RUN npm install --no-save sharp \
-    && node -e "require('sharp'); console.log('[build] sharp native bindings verified')"
-
-# node-pty distributes platform-specific native bindings as optional packages
-# (@lydell/node-pty-linux-x64) that npm prune removes. Reinstall after pruning.
-RUN npm install --no-save @lydell/node-pty \
-    && node -e "require('@lydell/node-pty'); console.log('[build] node-pty native bindings verified')"
-
-# =============================================================================
-# Stage 2: Production - Minimal runtime image
-# =============================================================================
-FROM node:20-bookworm-slim AS production
-
-WORKDIR /app
-
-# Install runtime dependencies only
-# libvips is needed for sharp image processing
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    libvips42 \
-    ca-certificates \
-    wget \
-    && rm -rf /var/lib/apt/lists/* \
-    && apt-get clean
-
-# Install Litestream for SQLite WAL replication to S3/GCS
-ARG TARGETARCH
-RUN wget -q "https://github.com/benbjohnson/litestream/releases/download/v0.3.13/litestream-v0.3.13-linux-${TARGETARCH:-amd64}.deb" -O /tmp/litestream.deb \
-    && dpkg -i /tmp/litestream.deb \
-    && rm /tmp/litestream.deb
-
-# Create non-root user for security
-RUN groupadd -r openhive && useradd -r -g openhive openhive
-
-# Copy built application from builder stage
-COPY --from=builder /app/dist ./dist
-COPY --from=builder /app/bin ./bin
-COPY --from=builder /app/node_modules ./node_modules
-COPY --from=builder /app/package.json ./
-
-# Copy entrypoint script (handles Litestream restore + replicate)
-COPY docker-entrypoint.sh /app/docker-entrypoint.sh
-
-# Create data directories with correct ownership
-RUN chmod +x /app/docker-entrypoint.sh && \
-    mkdir -p /app/data /app/uploads && \
-    chown -R openhive:openhive /app
-
-# Switch to non-root user
-USER openhive
-
-# Environment defaults
-ENV NODE_ENV=production \
-    OPENHIVE_HOST=0.0.0.0 \
-    OPENHIVE_PORT=3000 \
-    OPENHIVE_DATABASE=/app/data/openhive.db
-
-# Expose the default port
-EXPOSE 3000
-
-# Health check - verify the server is responding
-HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
-    CMD node -e "fetch('http://localhost:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
-
-# Start via entrypoint (handles Litestream if configured, else starts normally)
-CMD ["/app/docker-entrypoint.sh"]