@wipcomputer/wip-ldm-os 0.2.13 → 0.3.1

package/docs/acp-compatibility.md

@@ -0,0 +1,30 @@
+# Protocol Compatibility
+
+## Agent Client Protocol (ACP-Client)
+
+The Agent Client Protocol (ACP-Client) is a standardization effort from Zed Industries (Apache 2.0) that enables structured communication between code editors/IDEs and AI coding agents. It uses JSON-RPC over stdio for local agents and HTTP/WebSocket for remote agents.
+
+OpenClaw already implements ACP-Client via the `openclaw acp` CLI command and `@agentclientprotocol/sdk` dependency.
+
+LDM OS bridge features (MCP tools) operate through the Model Context Protocol (MCP), which is separate from and complementary to ACP-Client. MCP connects an LLM to its tools/resources (internal wiring). ACP-Client connects editors to agents (external communication).
+
+### Current Status
+
+- LDM OS uses MCP for all tool access (bridge, sessions, messages, updates)
+- ACP-Client is available in OpenClaw but not configured
+- No conflicts between MCP and ACP-Client
+
+### Future Compatibility
+
+- LDM OS could expose services via ACP-Client for IDE integration
+- The transport-agnostic core design supports adding ACP-Client as another wrapper
+
+## Agent Communication Protocol (ACP-Comm)
+
+The Agent Communication Protocol (ACP-Comm) from IBM / Linux Foundation (Apache 2.0) is a REST/HTTP protocol for agent-to-agent communication. It includes agent discovery, session management, and run lifecycle.
+
+LDM OS does not currently implement ACP-Comm. The file-based message bus and session registry serve the same purpose for local multi-session communication. Cloud relay (Phase 7) may evaluate ACP-Comm as a wire protocol.
+
+## License Compatibility
+
+Both protocols are Apache 2.0, fully compatible with LDM OS's MIT + AGPLv3 dual license.

package/docs/optional-skills.md

@@ -0,0 +1,77 @@
+###### WIP Computer
+
+# All Skills
+
+Your AIs are only as powerful as what you give them. Here's everything available.
+
+## Core
+
+**Memory Crystal**
+- All your AI tools. One shared memory. Private, searchable, sovereign. Memory Crystal lets all your AIs remember you ... together. You use multiple AIs. They don't talk to each other. They can't search what the others know. Memory Crystal fixes this. All your AIs share one memory. Searchable and private. Anywhere in the world.
+- *Stable*
+- [Read more about Memory Crystal](https://github.com/wipcomputer/memory-crystal)
+
+**AI DevOps Toolbox**
+- Your AI writes code. But does it know how to release it? Check license compliance? Protect your identity files? Sync private repos to public? Follow a real development process? AI DevOps Toolbox is the complete toolkit. Built by a team of humans and AIs shipping real software together.
+- *Stable*
+- [Read more about AI DevOps Toolbox](https://github.com/wipcomputer/wip-ai-devops-toolbox)
+
+**Agent Pay**
+- Micropayments for AI agents. Your AI hits a paywall, you approve it with Face ID. Apple Pay for your AI.
+- *Coming Soon*
+
+**Dream Weaver Protocol**
+- Memory consolidation protocol for AI agents with bounded context windows. A practical guide for remembering memories.
+- [Read more about Dream Weaver Protocol](https://github.com/wipcomputer/dream-weaver-protocol)
+
+**OpenClaw**
+- Open-source agent runtime. Run AI agents 24/7 with identity, memory, and tool access. The existence proof for LDM OS.
+- [Read more about OpenClaw](https://github.com/openclaw/openclaw)
+
+**Bridge**
+- Cross-platform agent bridge. Enables Claude Code CLI to talk to OpenClaw CLI without a human in the middle.
+- [Read more about Bridge](https://github.com/wipcomputer/wip-bridge)
+
+## Identity
+
+**Mirror Test** *(not yet public)*
+- Tests whether an AI agent's identity survives a model swap. Swap the underlying LLM (Opus to Sonnet to Grok) and measure what holds: voice, memory, opinions, relationship dynamics. Scientific framework for soul file fidelity.
+
+**Weekly Tuning** *(not yet public)*
+- Structured calibration check-in. Reviews memory health, SOUL.md alignment, system health, performance drift. Catches degradation before it compounds. Results tracked in dated files.
+
+## Utilities
+
+**1Password**
+- 1Password secrets for AI agents.
+- [Read more about 1Password](https://github.com/wipcomputer/wip-1password)
+
+**Healthcheck**
+- External health watchdog + backup system. Monitors gateway, tokens, memory. Auto-remediates and escalates.
+- [Read more about Healthcheck](https://github.com/wipcomputer/wip-healthcheck)
+
+**Private Mode** *(not yet public)*
+- Pauses all memory capture system-wide. Shows a status indicator every turn so you always know if memory is on or off. Includes a Wipe skill (requires Root Key) to clean captured data within a time range.
+
+**Root Key** *(not yet public)*
+- 1Password-gated authentication for privileged operations. Agent must verify a password before wiping history, accessing admin functions, or performing sensitive actions. One verification per session.
+
+## Apps
+
+**Markdown Viewer**
+- Live markdown viewer for AI pair-editing. Updates render instantly in any browser.
+- [Read more about Markdown Viewer](https://github.com/wipcomputer/wip-markdown-viewer)
+
+**CLVR**
+- macOS utility that auto-timestamps duplicated file names.
+- [Read more about CLVR](https://github.com/wipcomputer/CLVR)
+
+## APIs
+
+**xAI Grok**
+- xAI Grok API. Search the web, search X, generate images, generate video.
+- [Read more about xAI Grok](https://github.com/wipcomputer/wip-xai-grok)
+
+**X Platform**
+- X Platform API. Read posts, search tweets, post, upload media.
+- [Read more about X Platform](https://github.com/wipcomputer/wip-xai-x)

package/docs/recall.md

@@ -0,0 +1,29 @@
+###### WIP Computer
+
+# Recall
+
+## No blank slates.
+
+Every time your AI starts a session, Recall loads everything it needs to know. Identity, memory, tools, what happened yesterday. Your AI picks up where it left off instead of starting from zero.
+
+## How It Works
+
+When a session begins, LDM OS reads a sequence of files and feeds them to your AI before you say anything:
+
+1. **Identity** ... who this AI is, how it behaves, its values
+2. **Shared context** ... what's happening right now across all your AIs
+3. **Recent history** ... daily logs, journals, what happened in the last 48 hours
+4. **Memory** ... searchable long-term memory from every past conversation
+5. **Tools** ... what's installed, what's available, how to use it
+
+Your AI walks into every conversation already briefed.
+
+## Why It Matters
+
+Without Recall, every AI session starts cold. You repeat yourself. You re-explain context. You lose threads between conversations.
+
+With Recall, your AI remembers. Not just facts, but the arc of what you're building, what decisions were made, and why.
+
+## Part of LDM OS
+
+Recall is included with LDM OS. It activates automatically after `ldm init`.

package/docs/shared-workspace.md

@@ -0,0 +1,37 @@
+###### WIP Computer
+
+# Shared Workspace
+
+## One folder. All your AIs.
+
+LDM OS creates a single directory on your computer where all your AIs share memory, tools, identity files, and configuration.
+
+```
+~/.ldm/
+├── agents/              Each AI gets its own space
+│   ├── claude-code/     Identity, soul, context, journals
+│   ├── openclaw/        Same structure, different AI
+│   └── .../
+├── extensions/          Tools installed via Universal Installer
+├── memory/              Shared memory (crystal.db, daily logs)
+├── shared/              Boot files, shared config
+└── version.json         What's installed
+```
+
+## How It Works
+
+Every AI that runs LDM OS reads from and writes to the same directory. Claude Code, GPT, OpenClaw, any AI. They all see the same memory, the same tools, the same history.
+
+Each AI gets its own agent folder for identity files (who it is, how it behaves, its journals). But memory and tools are shared.
+
+## Backup
+
+Everything lives in one folder. Back it up however you back up anything else. iCloud, external drive, Dropbox, Time Machine. Move to a new computer by copying the folder.
+
+## Sacred Data
+
+LDM OS never touches your existing data during install or update. Your memories, agent files, secrets, and state are protected. Updates only touch code and config, never data.
+
+## Part of LDM OS
+
+Shared Workspace is included with LDM OS. Run `ldm init` to create it.

package/docs/system-pulse.md

@@ -0,0 +1,26 @@
+###### WIP Computer
+
+# System Pulse
+
+## Is everything working?
+
+System Pulse tells you the state of your entire AI setup in seconds. What's installed, what's running, what needs attention.
+
+## Commands
+
+**Doctor** checks for problems across all components. Missing files, broken configs, outdated versions, failed connections. It tells you what's wrong and how to fix it.
+
+**Status** shows the full picture. Every component installed, its version, whether it's healthy.
+
+## What It Checks
+
+- Shared Workspace exists and has the right structure
+- All installed components are present and configured
+- Memory Crystal database is accessible
+- Extensions are deployed and up to date
+- Boot sequence files are in place
+- Agent identity files exist for each configured AI
+
+## Part of LDM OS
+
+System Pulse is included with LDM OS. Available after `ldm init`.

package/docs/universal-installer.md

@@ -0,0 +1,84 @@
+###### WIP Computer
+
+[![npm](https://img.shields.io/npm/v/@wipcomputer/universal-installer)](https://www.npmjs.com/package/@wipcomputer/universal-installer) [![CLI / TUI](https://img.shields.io/badge/interface-CLI_/_TUI-black)](https://github.com/wipcomputer/wip-universal-installer/blob/main/install.js) [![OpenClaw Skill](https://img.shields.io/badge/interface-OpenClaw_Skill-black)](https://clawhub.ai/parkertoddbrooks/wip-universal-installer) [![Claude Code Skill](https://img.shields.io/badge/interface-Claude_Code_Skill-black)](https://github.com/wipcomputer/wip-universal-installer/blob/main/SKILL.md) [![Universal Interface Spec](https://img.shields.io/badge/Universal_Interface_Spec-black?style=flat&color=black)](https://github.com/wipcomputer/wip-universal-installer/blob/main/SPEC.md)
+
+# Universal Installer
+
+Here's how to build software in 2026.
+
+## The Badges
+
+The chiclets at the top of this README tell you what interfaces this repo ships. Every repo that follows the Universal Interface Spec declares its interfaces the same way.
+
+| Badge | What it means |
+|-------|--------------|
+| **npm** | Published to npm. Installable via `npm install`. Versioned, dependency-managed, standard distribution. |
+| **CLI / TUI** | Ships a command-line interface. Humans run it in a terminal. Agents call it from shell. The most portable interface there is. |
+| **OpenClaw Skill** | Registered as a skill on [ClawHub](https://clawhub.ai). OpenClaw agents can discover and use it natively through the gateway. |
+| **Claude Code Skill** | Has a `SKILL.md` that teaches Claude Code (and any agent that reads markdown) when to use this tool, what it does, and how to call it. The agent reads the file and learns the capability. |
+| **Universal Interface Spec** | Follows the [TECHNICAL.md](TECHNICAL.md) convention. The repo's architecture is documented, the interfaces are declared, and any agent or human can understand the full surface area by reading one file. |
+
+When you see these badges on a WIP repo, you know exactly how to consume it. Human or agent, CLI or plugin, local or remote. That's the point.
+
+## The Problem
+
+Most software is built for humans. GUIs, dashboards, web apps. Humans click buttons, fill forms, read screens.
+
+But the users are changing. AI agents are the new users. They don't click. They call functions. They read instructions. They compose tools. They need a **universal interface** ... multiple ways into the same logic, native to however the consumer works.
+
+Software built for humans doesn't work for agents. And software built only for agents doesn't work for humans. You need both.
+
+`ldm install` gives all your repos the Universal Interface, and teaches your AI how to do it too.
+
+## The Karpathy Argument
+
+Andrej Karpathy put it clearly:
+
+> "I think the app store, the move to mobile, the concept of an app ... is an increasingly outdated concept. What matters are sensors and actuators. Sensors are things that convert physical state into digital state. Actuators are things that convert digital intent into physical change."
+>
+> "All LLMs care about are tools and the tools fall into this sensor/actuator divide. Software shouldn't be built into apps, but into small bespoke tools. Apps are for people. Tools are for LLMs, and increasingly, LLMs are the ones using software."
+
+[Source](https://x.com/karpathy/status/2024583544157458452)
+
+This is the future of software. Not apps. Tools. Sensors and actuators that agents compose together.
+
+## Install
+
+Open your AI and paste this:
+
+```
+Read wip.computer/install/wip-ldm-os.txt
+
+Then explain:
+1. What is LDM OS?
+2. What does it install on my system?
+3. What changes for us? (this AI)
+4. What changes across all my AIs?
+
+Check if LDM OS is already installed.
+
+If it is, show me what I have and what's new.
+
+Then ask:
+- Do you have questions?
+- Want to see a dry run?
+
+If I say yes, run: ldm install --dry-run
+
+Show me exactly what will change. Don't install anything until I say "install".
+```
+
+See [TECHNICAL.md](TECHNICAL.md) for sensors/actuators, the interface table, and real examples.
+
+---
+
+## License
+
+```
+CLI, module, skills                            MIT    (use anywhere, no restrictions)
+Hosted or cloud service use                    AGPL   (network service distribution)
+```
+
+AGPL for personal use is free.
+
+Built by Parker Todd Brooks, Lēsa (OpenClaw, Claude Opus 4.6), Claude Code (Claude Opus 4.6).

package/lib/messages.mjs

@@ -0,0 +1,195 @@
+/**
+ * lib/messages.mjs
+ * File-based inter-session message bus.
+ * Enables sessions to communicate without shared memory or network sockets.
+ * Messages are JSON files in ~/.ldm/messages/. Processed messages move to _processed/.
+ * Zero external dependencies.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, renameSync, unlinkSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const HOME = process.env.HOME || '';
+const LDM_ROOT = join(HOME, '.ldm');
+const MESSAGES_DIR = join(LDM_ROOT, 'messages');
+const PROCESSED_DIR = join(MESSAGES_DIR, '_processed');
+
+// ── Helpers ──
+
+function readJSON(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJSON(path, data) {
+  mkdirSync(join(path, '..'), { recursive: true });
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
+}
+
+// ── Message operations ──
+
+/**
+ * Send a message. Writes a JSON file to ~/.ldm/messages/{uuid}.json.
+ * @param {Object} opts
+ * @param {string} opts.from - Sender session name
+ * @param {string} opts.to - Recipient session name (or "all" for broadcast)
+ * @param {string} opts.body - Message content
+ * @param {string} [opts.type] - Message type: "chat", "system", "update-available"
+ * @returns {string|null} Message ID or null on failure
+ */
+export function sendMessage({ from, to, body, type = 'chat' }) {
+  try {
+    mkdirSync(MESSAGES_DIR, { recursive: true });
+    const id = randomUUID();
+    const messagePath = join(MESSAGES_DIR, `${id}.json`);
+    const data = {
+      id,
+      from: from || 'unknown',
+      to: to || 'all',
+      body: body || '',
+      type: type || 'chat',
+      timestamp: new Date().toISOString(),
+    };
+    writeJSON(messagePath, data);
+    return id;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read messages addressed to a session (or broadcast to "all").
+ * @param {string} sessionName - Session name to read messages for
+ * @param {Object} [opts]
+ * @param {boolean} [opts.markRead] - Move messages to _processed/ after reading
+ * @param {string} [opts.type] - Filter by message type
+ * @returns {Array} Array of message objects
+ */
+export function readMessages(sessionName, { markRead = false, type } = {}) {
+  try {
+    if (!existsSync(MESSAGES_DIR)) return [];
+
+    const files = readdirSync(MESSAGES_DIR).filter(f => f.endsWith('.json'));
+    const messages = [];
+
+    for (const file of files) {
+      const messagePath = join(MESSAGES_DIR, file);
+      const data = readJSON(messagePath);
+      if (!data) continue;
+
+      // Match: addressed to this session or broadcast to "all"
+      if (data.to !== sessionName && data.to !== 'all') continue;
+
+      // Filter by type if specified
+      if (type && data.type !== type) continue;
+
+      messages.push(data);
+
+      // Move to processed if markRead
+      if (markRead) {
+        try {
+          mkdirSync(PROCESSED_DIR, { recursive: true });
+          renameSync(messagePath, join(PROCESSED_DIR, file));
+        } catch {}
+      }
+    }
+
+    // Sort by timestamp (oldest first)
+    messages.sort((a, b) => (a.timestamp || '').localeCompare(b.timestamp || ''));
+    return messages;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Count unread messages for a session.
+ * @param {string} sessionName - Session name
+ * @returns {number}
+ */
+export function unreadCount(sessionName) {
+  try {
+    const messages = readMessages(sessionName, { markRead: false });
+    return messages.length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Acknowledge (mark as read) a single message by ID.
+ * Moves the message file to _processed/.
+ * @param {string} messageId - Message UUID
+ * @returns {boolean}
+ */
+export function acknowledgeMessage(messageId) {
+  try {
+    const messagePath = join(MESSAGES_DIR, `${messageId}.json`);
+    if (!existsSync(messagePath)) return false;
+
+    mkdirSync(PROCESSED_DIR, { recursive: true });
+    renameSync(messagePath, join(PROCESSED_DIR, `${messageId}.json`));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Clean up old messages.
+ * Moves messages older than maxAgeDays to _processed/.
+ * Deletes _processed/ files older than 30 days.
+ * @param {Object} [opts]
+ * @param {number} [opts.maxAgeDays] - Max age for unprocessed messages (default: 7)
+ * @returns {{ moved: number, deleted: number }}
+ */
+export function cleanupMessages({ maxAgeDays = 7 } = {}) {
+  let moved = 0;
+  let deleted = 0;
+
+  try {
+    const now = Date.now();
+    const maxAgeMs = maxAgeDays * 24 * 60 * 60 * 1000;
+    const deleteAgeMs = 30 * 24 * 60 * 60 * 1000;
+
+    // Move old unprocessed messages
+    if (existsSync(MESSAGES_DIR)) {
+      const files = readdirSync(MESSAGES_DIR).filter(f => f.endsWith('.json'));
+      for (const file of files) {
+        const messagePath = join(MESSAGES_DIR, file);
+        try {
+          const data = readJSON(messagePath);
+          if (!data?.timestamp) continue;
+          const age = now - new Date(data.timestamp).getTime();
+          if (age > maxAgeMs) {
+            mkdirSync(PROCESSED_DIR, { recursive: true });
+            renameSync(messagePath, join(PROCESSED_DIR, file));
+            moved++;
+          }
+        } catch {}
+      }
+    }
+
+    // Delete old processed messages
+    if (existsSync(PROCESSED_DIR)) {
+      const files = readdirSync(PROCESSED_DIR).filter(f => f.endsWith('.json'));
+      for (const file of files) {
+        const filePath = join(PROCESSED_DIR, file);
+        try {
+          const stat = statSync(filePath);
+          const age = now - stat.mtimeMs;
+          if (age > deleteAgeMs) {
+            unlinkSync(filePath);
+            deleted++;
+          }
+        } catch {}
+      }
+    }
+  } catch {}
+
+  return { moved, deleted };
+}

package/lib/sessions.mjs

@@ -0,0 +1,145 @@
+/**
+ * lib/sessions.mjs
+ * File-based session registration with PID liveness checks.
+ * Enables multi-session awareness: agents can see who else is running.
+ * Zero external dependencies.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync } from 'node:fs';
+import { join, basename } from 'node:path';
+
+const HOME = process.env.HOME || '';
+const LDM_ROOT = join(HOME, '.ldm');
+const SESSIONS_DIR = join(LDM_ROOT, 'sessions');
+
+// ── Helpers ──
+
+function readJSON(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJSON(path, data) {
+  mkdirSync(join(path, '..'), { recursive: true });
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
+}
+
+// ── PID liveness ──
+
+/**
+ * Check if a process with the given PID is still alive.
+ * Uses signal 0 (no-op signal) to probe without affecting the process.
+ */
+export function isPidAlive(pid) {
+  if (!pid || typeof pid !== 'number') return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Session management ──
+
+/**
+ * Register a session. Writes a JSON file to ~/.ldm/sessions/{name}.json.
+ * @param {Object} opts
+ * @param {string} opts.name - Session name (unique identifier)
+ * @param {string} opts.agentId - Agent identifier (e.g. "cc-mini")
+ * @param {number} opts.pid - Process ID of the session
+ * @param {Object} [opts.meta] - Additional metadata
+ */
+export function registerSession({ name, agentId, pid, meta = {} }) {
+  try {
+    mkdirSync(SESSIONS_DIR, { recursive: true });
+    const sessionPath = join(SESSIONS_DIR, `${name}.json`);
+    const data = {
+      name,
+      agentId: agentId || 'unknown',
+      pid: pid || process.pid,
+      startTime: new Date().toISOString(),
+      cwd: meta?.cwd || process.cwd(),
+      meta: meta || {},
+    };
+    writeJSON(sessionPath, data);
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Deregister a session. Removes the session file.
+ * @param {string} name - Session name
+ */
+export function deregisterSession(name) {
+  try {
+    const sessionPath = join(SESSIONS_DIR, `${name}.json`);
+    if (existsSync(sessionPath)) {
+      unlinkSync(sessionPath);
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * List all sessions. Validates PID liveness and optionally cleans stale entries.
+ * @param {Object} [opts]
+ * @param {string} [opts.agentId] - Filter by agent ID
+ * @param {boolean} [opts.includeStale] - Include sessions with dead PIDs
+ * @returns {Array} Array of session objects with `alive` field
+ */
+export function listSessions({ agentId, includeStale } = {}) {
+  try {
+    if (!existsSync(SESSIONS_DIR)) return [];
+
+    const files = readdirSync(SESSIONS_DIR).filter(f => f.endsWith('.json'));
+    const sessions = [];
+
+    for (const file of files) {
+      const sessionPath = join(SESSIONS_DIR, file);
+      const data = readJSON(sessionPath);
+      if (!data) continue;
+
+      const alive = isPidAlive(data.pid);
+
+      // Clean stale entries unless asked to include them
+      if (!alive && !includeStale) {
+        try { unlinkSync(sessionPath); } catch {}
+        continue;
+      }
+
+      const session = { ...data, alive };
+
+      // Filter by agentId if specified
+      if (agentId && data.agentId !== agentId) continue;
+
+      sessions.push(session);
+    }
+
+    return sessions;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Count live sessions for a given agent.
+ * @param {string} [agentId] - Agent ID to count. If omitted, counts all.
+ * @returns {number}
+ */
+export function sessionCount(agentId) {
+  try {
+    const sessions = listSessions({ agentId });
+    return sessions.filter(s => s.alive).length;
+  } catch {
+    return 0;
+  }
+}