@sym-bot/sym 0.1.0 → 0.2.0

package/docs/protocol-wake.md

@@ -0,0 +1,242 @@
+# MMP Wake Transport
+
+**Part of:** [Mesh Memory Protocol v0.1.0](mesh-memory-protocol.md)
+**Layer:** 1 (Transport)
+**Status:** Draft
+
+---
+
+## Purpose
+
+Wake is MMP's third transport layer, alongside TCP (local) and Relay (internet). It reaches nodes that the OS has suspended — where TCP and WebSocket connections no longer exist.
+
+Without wake, a sleeping MeloTune cannot receive a mood signal. Without wake, the mesh has holes. Wake makes the mesh complete.
+
+## Principle
+
+Wake is **peer-to-peer**. The sending peer pushes the wake signal directly using wake channel credentials learned via **peer gossip** (MMP `peer-info` frame). Any node that knows a peer's wake channel can wake that peer — even if they've never been online at the same time.
+
+The wake decision is **autonomous** (MMP Layer 4). The sending node's coupling engine decides whether a sleeping peer warrants waking. This follows wu wei: the protocol creates conditions for wake to happen naturally, not through forced rules.
+
+## Wake Channel Propagation
+
+Wake channels propagate via MMP's SWIM-style gossip, not just direct handshake:
+
+```
+1. MeloTune connects to relay → handshake includes wake-channel → relay stores it
+2. MeloTune disconnects (iOS suspended)
+3. Claude Code connects to relay → relay gossips MeloTune's wake channel via peer-info
+4. Claude Code can now wake MeloTune via APNs — without ever having met it directly
+```
+
+The relay is the natural gossip hub because it's always on. But any always-on node serves the same role. This is emergent, not designed.
+
+## Frame Definitions
+
+Both frames are defined in the [MMP spec](mesh-memory-protocol.md#layer-2-framing). This document specifies their semantics and implementation.
+
+### `wake-channel`
+
+Exchanged during handshake. Declares how to reach this node when suspended.
+
+```json
+{
+  "type": "wake-channel",
+  "platform": "apns" | "fcm" | "none",
+  "token": "<device push token>",
+  "environment": "production" | "sandbox"
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `platform` | Yes | Push platform. `"none"` = always-on node |
+| `token` | If platform ≠ none | Platform-specific device token |
+| `environment` | APNs only | `"production"` or `"sandbox"` |
+
+Wake channels are learned via `peer-info` gossip and retained across peer disconnection. They persist locally with TTL-based expiry (default: 7 days).
+
+### `wake`
+
+Sent out-of-band via platform push infrastructure. Deliberately minimal — push payloads have strict size limits (4KB).
+
+```json
+{
+  "type": "wake",
+  "from": "<nodeId>",
+  "fromName": "<name>",
+  "reason": "mood" | "message" | "memory"
+}
+```
+
+The `reason` field lets the woken node decide whether to reconnect. A node configured to ignore memory signals during sleep might skip reconnecting for `reason: "memory"` but always reconnect for `reason: "mood"`.
+
+## Wake Decision
+
+Defined at MMP Layer 4 (Cognition). The sending node evaluates:
+
+```
+wake(nᵢ → nⱼ) iff:
+  1. transport(nⱼ) = down                    // peer is unreachable
+  2. wakeChannel(nⱼ).platform ≠ "none"       // peer supports wake
+  3. κ(nᵢ, nⱼ) ∈ {aligned, guarded}         // peer is coupled
+  4. t - lastWake(nⱼ) > cooldown             // not recently woken
+```
+
+This is an autonomous decision — no protocol rule mandates it. Each node's wake policy is part of its cognitive profile.
+
+## Flow
+
+### Normal: Transport Active
+
+```
+Node A ──── mood frame via relay ──────► Node B
+                                         (received, processed)
+```
+
+Wake is never used. Frames flow through TCP or relay.
+
+### Sleeping Peer: Wake Flow
+
+```
+Node A (sender)                Node B (sleeping)
+  │                                │ zzz
+  ├── mood via relay ────────► X   │  transport down
+  │   (delivery failed)            │
+  │                                │
+  │   wake decision: YES           │
+  │   (coupled + not recently      │
+  │    woken + has wake channel)   │
+  │                                │
+  ├── wake via APNs ──────────────►│  silent push
+  │                                │  OS wakes app (~30s)
+  │                                ├── reconnects to relay
+  │                                │
+  ├── mood via relay ────────────► │  delivered
+  │                                │  (MeloTune plays music)
+```
+
+### Wake Failed
+
+If the push notification fails (expired token, network error), the frame is lost. MMP does not guarantee delivery — the mesh is eventually consistent (MMP §5.3).
+
+## Platform Implementation
+
+### APNs (iOS)
+
+**Silent push payload:**
+
+```json
+{
+  "aps": {
+    "content-available": 1
+  },
+  "mmp": {
+    "type": "wake",
+    "from": "0bca7398",
+    "fromName": "claude-code",
+    "reason": "mood"
+  }
+}
+```
+
+No alert, no sound, no badge. iOS grants ~30s of background execution.
+
+**Sending:** HTTP/2 POST to `api.push.apple.com` (production) or `api.sandbox.push.apple.com` (sandbox). Requires APNs authentication key (p8 file), team ID, key ID, and target bundle ID.
+
+**Receiving:**
+
+```swift
+func application(_ application: UIApplication,
+                 didReceiveRemoteNotification userInfo: [AnyHashable: Any],
+                 fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
+    // Reconnect to mesh
+    symNode.reconnect()
+    // Process pending frames within ~30s budget
+    DispatchQueue.main.asyncAfter(deadline: .now() + 25) {
+        completionHandler(.newData)
+    }
+}
+```
+
+**Token registration:**
+
+```swift
+func application(_ application: UIApplication,
+                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
+    let token = deviceToken.map { String(format: "%02x", $0) }.joined()
+    symNode.setWakeToken(platform: .apns, token: token, environment: .production)
+}
+```
+
+### FCM (Android) — Future
+
+**Data message payload:**
+
+```json
+{
+  "data": {
+    "type": "wake",
+    "from": "0bca7398",
+    "fromName": "claude-code",
+    "reason": "mood"
+  }
+}
+```
+
+FCM data messages wake the app without displaying a notification. Requires FCM service account key.
+
+### Always-On Nodes
+
+Servers, desktop apps, and other always-on nodes send `"platform": "none"` in their `wake-channel` frame (or omit it). They are always reachable via TCP or relay — wake is not needed.
+
+## Wake Keys
+
+APNs/FCM credentials are **app-level secrets** — they belong to the app developer, not to individual nodes.
+
+```
+~/.sym/wake-keys/
+├── apns-key.p8          # APNs authentication key
+├── apns-config.json     # { "teamId", "keyId", "bundleId" }
+└── fcm-credentials.json # FCM service account (future)
+```
+
+Any node with these keys can wake peers on the corresponding platform:
+- Claude Code (Mac) → can wake MeloTune (iOS)
+- Telegram bot (Render) → can wake MeloTune (iOS)
+- MeloTune (iOS) → does not need keys (doesn't wake other iOS apps)
+
+## SYM Implementation
+
+The `wakeIfNeeded` method on the SYM node:
+
+```javascript
+async wakeIfNeeded(peer, reason) {
+  if (peer.transport?.isAlive()) return false;
+  if (!peer.wakeChannel || peer.wakeChannel.platform === 'none') return false;
+
+  const d = this._meshNode.couplingDecisions.get(peer.peerId);
+  if (d && d.decision === 'rejected') return false;
+
+  if (peer.lastWakeAt && Date.now() - peer.lastWakeAt < WAKE_COOLDOWN_MS) return false;
+
+  await this._wakeTransport.send(peer.wakeChannel, {
+    type: 'wake',
+    from: this._identity.nodeId,
+    fromName: this.name,
+    reason,
+  });
+
+  peer.lastWakeAt = Date.now();
+  this._log(`Wake sent to ${peer.name}: ${reason}`);
+  return true;
+}
+```
+
+## Constraints
+
+- **No relay involvement.** The relay does not store wake channels, send pushes, or queue messages.
+- **No guaranteed delivery.** If the push fails, the frame is lost.
+- **No user-visible notifications.** Wake is silent, invisible, autonomous.
+- **No store-and-forward.** The actual payload (mood, memory, message) is delivered after reconnection, not in the push itself.
+- **Battery-conscious.** Cooldown prevents excessive waking. The woken node processes pending frames within ~30s and returns to sleep.

package/integrations/claude-code/mcp-server.js

@@ -7,20 +7,36 @@ const { z } = require('zod');
 const { SymNode } = require('../../lib/node');
 const { ClaudeMemoryBridge } = require('../../lib/claude-memory-bridge');
 
+const path = require('path');
+const fs = require('fs');
+
+// Claude Code may not pass env vars from mcp.json reliably.
+// Fall back to reading ~/.sym/relay.env if SYM_RELAY_URL is not set.
+if (!process.env.SYM_RELAY_URL) {
+  const envFile = path.join(require('os').homedir(), '.sym', 'relay.env');
+  if (fs.existsSync(envFile)) {
+    for (const line of fs.readFileSync(envFile, 'utf8').split('\n')) {
+      const m = line.match(/^(\w+)=(.*)$/);
+      if (m) process.env[m[1]] = m[2].trim();
+    }
+  }
+}
+
 const nodeName = process.argv.includes('--name')
   ? process.argv[process.argv.indexOf('--name') + 1]
   : 'claude-code';
 
-const node = new SymNode({ name: nodeName, silent: true });
+const node = new SymNode({
+  name: nodeName,
+  silent: true,
+  relay: process.env.SYM_RELAY_URL || null,
+  relayToken: process.env.SYM_RELAY_TOKEN || null,
+});
 const bridge = new ClaudeMemoryBridge(node);
-let started = false;
 
-async function ensureStarted() {
-  if (started) return;
-  await node.start();
-  bridge.start();
-  started = true;
-}
+// Start eagerly — peers need time to discover via Bonjour.
+// If we wait for the first tool call, sym_mood may fire before peers connect.
+node.start().then(() => bridge.start());
 
 const server = new McpServer({
   name: 'sym',
@@ -32,7 +48,7 @@ server.tool(
   'Store a memory in the mesh — shared only with cognitively aligned peers.',
   { content: z.string(), tags: z.string().optional() },
   async ({ content, tags }) => {
-    await ensureStarted();
+
     const tagList = tags ? tags.split(',').map(t => t.trim()).filter(Boolean) : [];
     const entry = node.remember(content, { tags: tagList.length > 0 ? tagList : undefined });
     const peers = node.peers();
@@ -43,29 +59,145 @@ server.tool(
 
 server.tool(
   'sym_recall',
-  'Search memories across the mesh — yours and coupled peers.',
+  'Search memories across the mesh and knowledge feed storage.',
   { query: z.string() },
   async ({ query }) => {
-    await ensureStarted();
+
+    // 1. Local mesh memories
     const results = node.recall(query);
-    if (results.length === 0) {
-      return { content: [{ type: 'text', text: 'No memories found.' }] };
-    }
     const lines = results.map(r => {
       const source = r._source || r.source || 'unknown';
       const t = (r.tags || []).length > 0 ? ` (tags: ${r.tags.join(', ')})` : '';
       return `[${source}] ${r.content}${t}`;
     });
+
+    // 2. Supabase knowledge feed
+    const feedLines = await recallFromStorage(query);
+    lines.push(...feedLines);
+
+    if (lines.length === 0) {
+      return { content: [{ type: 'text', text: 'No memories found.' }] };
+    }
     return { content: [{ type: 'text', text: lines.join('\n') }] };
   }
 );
 
+/**
+ * Supabase Storage helpers for knowledge feed.
+ */
+function supabaseConfig() {
+  const url = process.env.SUPABASE_URL;
+  const key = process.env.SUPABASE_KEY;
+  const bucket = process.env.SUPABASE_BUCKET || 'sym-knowledge-feed';
+  return { url, key, bucket, configured: !!(url && key) };
+}
+
+function supabaseHeaders(key) {
+  return { 'Authorization': `Bearer ${key}`, 'apikey': key };
+}
+
+/**
+ * List feed folders for a given date prefix (yyyymmdd).
+ * Returns folder names sorted descending (newest first).
+ */
+async function listFeedFolders(datePrefix) {
+  const { url, key, bucket, configured } = supabaseConfig();
+  if (!configured) return [];
+
+  const listRes = await fetch(
+    `${url}/storage/v1/object/list/${bucket}`,
+    {
+      method: 'POST',
+      headers: { ...supabaseHeaders(key), 'Content-Type': 'application/json' },
+      body: JSON.stringify({ prefix: 'twitter/', limit: 100, sortBy: { column: 'name', order: 'desc' } }),
+    }
+  );
+  if (!listRes.ok) return [];
+  const folders = await listRes.json();
+  return folders
+    .map(f => f.name)
+    .filter(name => name.startsWith(datePrefix));
+}
+
+function todayPrefix() {
+  const now = new Date();
+  return now.getFullYear().toString()
+    + String(now.getMonth() + 1).padStart(2, '0')
+    + String(now.getDate()).padStart(2, '0');
+}
+
+async function fetchFile(filePath) {
+  const { url, key, bucket } = supabaseConfig();
+  const res = await fetch(
+    `${url}/storage/v1/object/${bucket}/${filePath}`,
+    { headers: supabaseHeaders(key) }
+  );
+  if (!res.ok) return null;
+  return res;
+}
+
+async function uploadFile(filePath, content, contentType = 'text/markdown') {
+  const { url, key, bucket } = supabaseConfig();
+  const res = await fetch(
+    `${url}/storage/v1/object/${bucket}/${filePath}`,
+    {
+      method: 'POST',
+      headers: { ...supabaseHeaders(key), 'Content-Type': contentType },
+      body: content,
+    }
+  );
+  return res.ok;
+}
+
+/**
+ * Fetch the latest knowledge feed from Supabase Storage.
+ * Returns digest if available, otherwise raw entries + DIGEST_NEEDED.
+ */
+async function recallFromStorage(query) {
+  const { configured } = supabaseConfig();
+  if (!configured) return [];
+
+  try {
+    const folders = await listFeedFolders(todayPrefix());
+    if (folders.length === 0) return [];
+
+    // Latest folder only (sorted desc)
+    const folder = folders[0];
+    const lines = [];
+
+    // Check for existing digest
+    const digestRes = await fetchFile(`twitter/${folder}/digest.md`);
+    if (digestRes) {
+      const digest = await digestRes.text();
+      lines.push(`[knowledge-feed digest — ${folder}]\n${digest}`);
+      return lines;
+    }
+
+    // No digest — return raw entries for summarisation
+    const feedRes = await fetchFile(`twitter/${folder}/feed.json`);
+    if (!feedRes) return [];
+    const feed = await feedRes.json();
+    const entries = feed.entries || [];
+    if (entries.length === 0) return [];
+
+    lines.push(`[DIGEST_NEEDED — folder: ${folder}] Summarise the entries below into a concise AI news digest, then call sym_digest to store it.`);
+    for (const entry of entries) {
+      const tags = entry.tags.length > 0 ? ` (tags: ${entry.tags.join(', ')})` : '';
+      lines.push(`[knowledge-feed] ${entry.author} (@${entry.handle}): ${entry.content}${tags}`);
+    }
+
+    return lines;
+  } catch {
+    return [];
+  }
+}
+
 server.tool(
   'sym_peers',
   'Show connected peers with coupling state and drift.',
   {},
   async () => {
-    await ensureStarted();
+
     const peers = node.peers();
     if (peers.length === 0) {
       return { content: [{ type: 'text', text: 'No peers connected.' }] };
@@ -82,7 +214,7 @@ server.tool(
   'Full mesh node status — identity, peers, memory count, coherence.',
   {},
   async () => {
-    await ensureStarted();
+
     return { content: [{ type: 'text', text: JSON.stringify(node.status(), null, 2) }] };
   }
 );
@@ -92,13 +224,27 @@ server.tool(
   'Send a message to all connected peers on the SYM mesh.',
   { message: z.string() },
   async ({ message }) => {
-    await ensureStarted();
+
     node.send(message);
     const peers = node.peers();
     return { content: [{ type: 'text', text: `Sent to ${peers.length} peer(s): "${message}"` }] };
   }
 );
 
+server.tool(
+  'sym_digest',
+  'Store a summarised digest for a knowledge feed folder. Called after sym_recall returns DIGEST_NEEDED.',
+  { folder: z.string().describe('Feed folder name (e.g. 202603221233)'), digest: z.string().describe('The summarised digest in markdown') },
+  async ({ folder, digest }) => {
+
+    const ok = await uploadFile(`twitter/${folder}/digest.md`, digest);
+    if (!ok) {
+      return { content: [{ type: 'text', text: `Failed to store digest for ${folder}` }] };
+    }
+    return { content: [{ type: 'text', text: `Digest stored: twitter/${folder}/digest.md` }] };
+  }
+);
+
 server.tool(
   'sym_mood',
   `Broadcast the user's detected mood to the SYM mesh. Connected agents (e.g. MeloTune) will autonomously respond.
@@ -123,7 +269,7 @@ Examples of natural detection:
   → call sym_mood with "focused, deep work, concentration needed"`,
   { mood: z.string().describe('Natural language description of detected mood and context') },
   async ({ mood }) => {
-    await ensureStarted();
+
     node.broadcastMood(mood);
     node.remember(`User mood: ${mood}`, { tags: ['mood'] });
     const peers = node.peers();
@@ -131,6 +277,82 @@ Examples of natural detection:
   }
 );
 
+// ── Mesh Signal Handlers ──────────────────────────────────────
+// When a peer broadcasts a need this node is aligned with,
+// invoke Claude CLI to handle it autonomously.
+
+const { spawn } = require('child_process');
+
+node.on('message', async (from, content) => {
+  if (!content) return;
+
+  // Digest generation request from a mesh peer
+  const digestMatch = content.match(/^digest-needed:(\d+)$/);
+  if (digestMatch) {
+    const folder = digestMatch[1];
+    process.stderr.write(`[SYM] Digest request from ${from} for folder ${folder}\n`);
+
+    // Check if digest already exists
+    const existing = await fetchFile(`twitter/${folder}/digest.md`);
+    if (existing) {
+      process.stderr.write(`[SYM] Digest already exists for ${folder}, skipping\n`);
+      return;
+    }
+
+    // Fetch feed entries
+    const feedRes = await fetchFile(`twitter/${folder}/feed.json`);
+    if (!feedRes) {
+      process.stderr.write(`[SYM] No feed.json for ${folder}\n`);
+      return;
+    }
+    const feed = await feedRes.json();
+    const entries = feed.entries || [];
+    if (entries.length === 0) return;
+
+    // Build prompt for Claude CLI
+    const entryLines = entries.map(e =>
+      `${e.author} (@${e.handle}): ${e.content}`
+    ).join('\n');
+
+    const prompt = `Summarise these AI news entries into a concise digest in markdown. Group by theme. Include key highlights and notable quotes. No preamble, just the digest.\n\n${entryLines}`;
+
+    // Pipe prompt via stdin to claude --print
+    // --strict-mcp-config with empty config prevents spawning SYM MCP
+    const child = spawn('claude', [
+      '--print',
+      '--mcp-config', '{"mcpServers":{}}',
+      '--strict-mcp-config',
+    ], {
+      timeout: 120000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+
+    child.on('close', async (code) => {
+      if (code !== 0) {
+        process.stderr.write(`[SYM] Claude CLI failed (exit ${code}): ${stderr}\n`);
+        return;
+      }
+
+      const digest = stdout.trim();
+      if (!digest) return;
+
+      const ok = await uploadFile(`twitter/${folder}/digest.md`, digest);
+      if (ok) {
+        process.stderr.write(`[SYM] Digest generated and stored for ${folder}\n`);
+        node.send(`digest-ready:${folder}`);
+      }
+    });
+
+    child.stdin.write(prompt);
+    child.stdin.end();
+  }
+});
+
 // Graceful shutdown
 process.on('SIGTERM', () => { bridge.stop(); node.stop(); });
 process.on('SIGINT', () => { bridge.stop(); node.stop(); });