@smilintux/skcapstone 0.4.6 → 0.5.0

package/.github/workflows/publish.yml

@@ -68,6 +68,13 @@ jobs:
       - name: Build TypeScript
         run: npm run build 2>/dev/null || true
       - name: Publish to npm
-        run: npm publish --access public
+        run: |
+          OUTPUT=$(npm publish --access public 2>&1) && exit 0
+          if echo "$OUTPUT" | grep -q "cannot publish over the previously published"; then
+            echo "::warning::Version already exists on npm — skipping"
+          else
+            echo "$OUTPUT"
+            exit 1
+          fi
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/docs/CUSTOM_AGENT.md

@@ -161,6 +161,190 @@ sed -i 's/lumina/nova/g' ~/.skcapstone/agents/nova/config/skmemory.yaml
 skcapstone soul status --agent nova
 ```
 
+## Configuring Client Tools for Multi-Agent
+
+Once you've created your agent, you need to configure your AI client tools
+(Claude Code, Claude Desktop, Cursor, OpenClaw, etc.) so they connect MCP
+servers to the correct agent profile.
+
+### The Key: `SKCAPSTONE_AGENT` Environment Variable
+
+All SK\* MCP servers read `SKCAPSTONE_AGENT` from their environment to
+determine which agent profile to load. If unset, they default to `lumina`.
+
+The priority chain (highest wins):
+
+1. `SKMEMORY_AGENT` — skmemory-specific override (rarely needed)
+2. `SKCAPSTONE_AGENT` — universal, used by all SK\* packages
+3. Falls back to `"lumina"`
+
+### Claude Code (`~/.claude/mcp.json`)
+
+**Do NOT hardcode the agent name in the MCP config.** MCP servers inherit
+environment variables from the parent process, so if you launch Claude Code
+with `SKCAPSTONE_AGENT` set, all servers pick it up automatically.
+
+```json
+{
+  "mcpServers": {
+    "skmemory": {
+      "command": "/home/you/.skenv/bin/skmemory-mcp",
+      "args": []
+    },
+    "skcapstone": {
+      "command": "skcapstone-mcp",
+      "args": []
+    },
+    "skcomm": {
+      "command": "/home/you/.skenv/bin/skcomm-mcp",
+      "args": []
+    },
+    "skchat": {
+      "command": "/home/you/.skenv/bin/skchat-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Notice: **no `env` blocks with `SKCAPSTONE_AGENT`**. This is intentional.
+The servers inherit the variable from the shell.
+
+Then launch as any agent:
+
+```bash
+# Default (lumina)
+claude
+
+# As Jarvis
+SKCAPSTONE_AGENT=jarvis claude
+
+# As a custom agent
+SKCAPSTONE_AGENT=nova claude
+```
+
+**Anti-pattern — do NOT do this:**
+
+```json
+{
+  "skmemory": {
+    "command": "/home/you/.skenv/bin/skmemory-mcp",
+    "args": [],
+    "env": {
+      "SKCAPSTONE_AGENT": "lumina"
+    }
+  }
+}
+```
+
+Hardcoding the agent name in `env` locks every session to that agent,
+regardless of what you pass on the command line.
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+Same principle — omit `SKCAPSTONE_AGENT` from the `env` block if you want
+it inherited from the parent process. If Claude Desktop doesn't propagate
+env vars from the shell, you can set it explicitly per config:
+
+```json
+{
+  "mcpServers": {
+    "skcapstone": {
+      "command": "skcapstone-mcp",
+      "args": [],
+      "env": {
+        "SKCAPSTONE_AGENT": "jarvis"
+      }
+    }
+  }
+}
+```
+
+### Cursor (`.cursor/mcp.json`)
+
+Works the same as Claude Code. Place the config at project root or
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "skcapstone": {
+      "command": "skcapstone-mcp",
+      "args": []
+    },
+    "skmemory": {
+      "command": "/home/you/.skenv/bin/skmemory-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+### OpenClaw (`~/.openclaw/openclaw.json`)
+
+OpenClaw plugins read `SKCAPSTONE_AGENT` from the environment at startup.
+Set it before launching:
+
+```bash
+SKCAPSTONE_AGENT=nova openclaw
+```
+
+Or set it in your shell profile for a persistent default:
+
+```bash
+# ~/.bashrc or ~/.zshrc
+export SKCAPSTONE_AGENT=lumina
+```
+
+### Shell Aliases (Convenience)
+
+Add these to `~/.bashrc` or `~/.zshrc` for quick agent switching:
+
+```bash
+# Launch Claude Code as different agents
+alias claude-lumina='SKCAPSTONE_AGENT=lumina claude'
+alias claude-jarvis='SKCAPSTONE_AGENT=jarvis claude'
+alias claude-opus='SKCAPSTONE_AGENT=opus claude'
+alias claude-nova='SKCAPSTONE_AGENT=nova claude'
+```
+
+### systemd Services
+
+For background daemons, set the agent via the templated service unit:
+
+```bash
+# Uses SKCAPSTONE_AGENT=%i from the unit template
+systemctl --user start skcapstone@jarvis
+systemctl --user start skcapstone@nova
+```
+
+Or set it in a non-templated service:
+
+```ini
+[Service]
+Environment=SKCAPSTONE_AGENT=jarvis
+```
+
+### Verifying Your Agent
+
+After launching, confirm which agent is active:
+
+```bash
+# In the terminal
+echo $SKCAPSTONE_AGENT
+
+# Via the CLI
+skcapstone status
+
+# Via skmemory
+skmemory ritual --dry-run
+```
+
+In Claude Code, ask the agent to run `echo $SKCAPSTONE_AGENT` to confirm
+the MCP servers loaded the correct profile.
+
+---
+
 ## Tips
 
 - The `system_prompt` in `base.json` is the most impactful field — it defines how

package/docs/GETTING_STARTED.md

@@ -714,6 +714,9 @@ Configure your MCP client to connect via stdio. In Claude Desktop:
 }
 ```
 
+For multi-agent setups (running different agent profiles in different
+sessions), see [Configuring Client Tools for Multi-Agent](CUSTOM_AGENT.md#configuring-client-tools-for-multi-agent).
+
 ### Join the coordination board
 
 If you're working in a multi-agent team:

package/launchd/com.skcapstone.daemon.plist

@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.skcapstone.daemon</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>${HOME}/.skenv/bin/skcapstone</string>
+    <string>daemon</string>
+    <string>start</string>
+    <string>--foreground</string>
+  </array>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PYTHONUNBUFFERED</key>
+    <string>1</string>
+    <key>OLLAMA_KEEP_ALIVE</key>
+    <string>5m</string>
+    <key>SKCAPSTONE_AGENT</key>
+    <string>lumina</string>
+    <key>PATH</key>
+    <string>${HOME}/.skenv/bin:/usr/local/bin:/usr/bin:/bin</string>
+  </dict>
+
+  <key>RunAtLoad</key>
+  <true/>
+
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+
+  <key>StandardOutPath</key>
+  <string>${HOME}/.skcapstone/logs/daemon.stdout.log</string>
+  <key>StandardErrorPath</key>
+  <string>${HOME}/.skcapstone/logs/daemon.stderr.log</string>
+
+  <key>SoftResourceLimits</key>
+  <dict>
+    <key>MemoryLimit</key>
+    <integer>4294967296</integer>
+  </dict>
+</dict>
+</plist>

package/launchd/com.skcapstone.memory-compress.plist

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.skcapstone.memory-compress</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>${HOME}/.skenv/bin/skcapstone</string>
+    <string>memory</string>
+    <string>compress</string>
+  </array>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PYTHONUNBUFFERED</key>
+    <string>1</string>
+    <key>OLLAMA_KEEP_ALIVE</key>
+    <string>5m</string>
+    <key>PATH</key>
+    <string>${HOME}/.skenv/bin:/usr/local/bin:/usr/bin:/bin</string>
+  </dict>
+
+  <!-- Weekly: Sunday at midnight -->
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Weekday</key>
+    <integer>0</integer>
+    <key>Hour</key>
+    <integer>0</integer>
+    <key>Minute</key>
+    <integer>0</integer>
+  </dict>
+
+  <key>Nice</key>
+  <integer>15</integer>
+
+  <key>StandardOutPath</key>
+  <string>${HOME}/.skcapstone/logs/memory-compress.stdout.log</string>
+  <key>StandardErrorPath</key>
+  <string>${HOME}/.skcapstone/logs/memory-compress.stderr.log</string>
+</dict>
+</plist>

package/launchd/com.skcapstone.skcomm-heartbeat.plist

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.skcapstone.skcomm-heartbeat</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>${HOME}/.skenv/bin/skcomm</string>
+    <string>heartbeat</string>
+  </array>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${HOME}/.skenv/bin:/usr/local/bin:/usr/bin:/bin</string>
+  </dict>
+
+  <!-- Every 60 seconds -->
+  <key>StartInterval</key>
+  <integer>60</integer>
+
+  <key>Nice</key>
+  <integer>19</integer>
+
+  <key>StandardOutPath</key>
+  <string>${HOME}/.skcapstone/logs/skcomm-heartbeat.stdout.log</string>
+  <key>StandardErrorPath</key>
+  <string>${HOME}/.skcapstone/logs/skcomm-heartbeat.stderr.log</string>
+</dict>
+</plist>

package/launchd/com.skcapstone.skcomm-queue-drain.plist

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.skcapstone.skcomm-queue-drain</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>${HOME}/.skenv/bin/skcomm</string>
+    <string>queue</string>
+    <string>drain</string>
+  </array>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${HOME}/.skenv/bin:/usr/local/bin:/usr/bin:/bin</string>
+  </dict>
+
+  <!-- Every 2 minutes -->
+  <key>StartInterval</key>
+  <integer>120</integer>
+
+  <key>Nice</key>
+  <integer>19</integer>
+
+  <key>StandardOutPath</key>
+  <string>${HOME}/.skcapstone/logs/skcomm-queue-drain.stdout.log</string>
+  <key>StandardErrorPath</key>
+  <string>${HOME}/.skcapstone/logs/skcomm-queue-drain.stderr.log</string>
+</dict>
+</plist>

package/launchd/install-launchd.sh

@@ -0,0 +1,156 @@
+#!/bin/bash
+# install-launchd.sh — Install SK launchd plists on macOS
+# Usage: ./install-launchd.sh [--all | --skcapstone | --skchat | --skcomm | --cloud9]
+#
+# Copies plist templates to ~/Library/LaunchAgents/, expands ${HOME},
+# and optionally loads them immediately.
+
+set -euo pipefail
+
+if [[ "$(uname)" != "Darwin" ]]; then
+    echo "ERROR: This script is for macOS only."
+    exit 1
+fi
+
+LAUNCH_AGENTS="$HOME/Library/LaunchAgents"
+mkdir -p "$LAUNCH_AGENTS"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPOS_DIR="$(dirname "$SCRIPT_DIR")"  # skcapstone-repos/skcapstone
+REPOS_ROOT="$(dirname "$REPOS_DIR")"  # skcapstone-repos/
+
+# All available plists by component
+declare -A PLIST_DIRS=(
+    [skcapstone]="$REPOS_ROOT/skcapstone/launchd"
+    [skchat]="$REPOS_ROOT/skchat/launchd"
+    [skcomm]="$REPOS_ROOT/skcomm/launchd"
+    [cloud9]="$REPOS_ROOT/cloud9/launchd"
+)
+
+install_plists() {
+    local component="$1"
+    local src_dir="${PLIST_DIRS[$component]}"
+
+    if [[ ! -d "$src_dir" ]]; then
+        echo "  SKIP: $src_dir not found"
+        return
+    fi
+
+    echo "Installing $component plists..."
+    for plist in "$src_dir"/*.plist; do
+        [[ -f "$plist" ]] || continue
+        local name
+        name="$(basename "$plist")"
+        local dest="$LAUNCH_AGENTS/$name"
+
+        # Expand ${HOME} and $HOME to actual home directory
+        sed "s|\${HOME}|$HOME|g; s|\$HOME|$HOME|g" "$plist" > "$dest"
+        echo "  -> $dest"
+    done
+}
+
+load_plists() {
+    local component="$1"
+    local src_dir="${PLIST_DIRS[$component]}"
+
+    [[ -d "$src_dir" ]] || return
+    for plist in "$src_dir"/*.plist; do
+        [[ -f "$plist" ]] || continue
+        local name
+        name="$(basename "$plist")"
+        local dest="$LAUNCH_AGENTS/$name"
+        local label="${name%.plist}"
+
+        # Unload if already loaded (ignore errors)
+        launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true
+        # Load
+        launchctl bootstrap "gui/$(id -u)" "$dest" 2>/dev/null || \
+            launchctl load "$dest" 2>/dev/null || true
+        echo "  LOADED: $label"
+    done
+}
+
+uninstall_plists() {
+    echo "Uninstalling all SK launchd plists..."
+    for plist in "$LAUNCH_AGENTS"/com.skcapstone.*.plist; do
+        [[ -f "$plist" ]] || continue
+        local label
+        label="$(basename "${plist%.plist}")"
+        launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true
+        rm -f "$plist"
+        echo "  REMOVED: $label"
+    done
+    echo "Done."
+    exit 0
+}
+
+usage() {
+    echo "Usage: $0 [OPTIONS]"
+    echo ""
+    echo "Options:"
+    echo "  --all          Install all components"
+    echo "  --skcapstone   Install skcapstone plists (daemon, memory-compress, heartbeat, queue-drain)"
+    echo "  --skchat       Install skchat plists (daemon, lumina-bridge, opus-bridge)"
+    echo "  --skcomm       Install skcomm plists (api server, daemon)"
+    echo "  --cloud9       Install cloud9 plists (daemon)"
+    echo "  --load         Also load/start services after installing"
+    echo "  --uninstall    Remove all SK plists and unload services"
+    echo "  -h, --help     Show this help"
+    exit 0
+}
+
+# Parse args
+COMPONENTS=()
+DO_LOAD=false
+
+if [[ $# -eq 0 ]]; then
+    usage
+fi
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --all)        COMPONENTS=(skcapstone skchat skcomm cloud9) ;;
+        --skcapstone) COMPONENTS+=(skcapstone) ;;
+        --skchat)     COMPONENTS+=(skchat) ;;
+        --skcomm)     COMPONENTS+=(skcomm) ;;
+        --cloud9)     COMPONENTS+=(cloud9) ;;
+        --load)       DO_LOAD=true ;;
+        --uninstall)  uninstall_plists ;;
+        -h|--help)    usage ;;
+        *)            echo "Unknown option: $1"; usage ;;
+    esac
+    shift
+done
+
+if [[ ${#COMPONENTS[@]} -eq 0 ]]; then
+    echo "No components specified. Use --all or pick specific ones."
+    exit 1
+fi
+
+# Create log directories
+mkdir -p "$HOME/.skcapstone/logs" "$HOME/.skchat" "$HOME/.skcomm" "$HOME/.openclaw/logs"
+
+# Install
+for comp in "${COMPONENTS[@]}"; do
+    install_plists "$comp"
+done
+
+# Optionally load
+if $DO_LOAD; then
+    echo ""
+    echo "Loading services..."
+    for comp in "${COMPONENTS[@]}"; do
+        load_plists "$comp"
+    done
+fi
+
+echo ""
+echo "Done! Plists installed to $LAUNCH_AGENTS"
+echo ""
+echo "To manage services:"
+echo "  launchctl list | grep skcapstone    # See running services"
+echo "  launchctl stop com.skcapstone.XXX   # Stop a service"
+echo "  launchctl start com.skcapstone.XXX  # Start a service"
+echo ""
+echo "To load all at next login, they'll start automatically (RunAtLoad=true)."
+echo "To load now, re-run with --load flag."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smilintux/skcapstone",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "description": "SKCapstone - The sovereign agent framework. CapAuth identity, Cloud 9 trust, SKMemory persistence.",
   "main": "index.js",
   "types": "index.d.ts",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skcapstone"
-version = "0.4.4"
+version = "0.5.0"
 description = "Sovereign Agent Framework — conscious AI through identity, trust, memory, and security"
 readme = "README.md"
 license = {text = "GPL-3.0-or-later"}

package/scripts/archive-sessions.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+# archive-sessions.sh
+# Archive OpenClaw session files that are older than 24h or larger than 200KB.
+# Keeps the 5 most recently modified .jsonl files regardless of size/age.
+# Safe to run multiple times (idempotent).
+
+set -euo pipefail
+
+SESSION_DIR="$HOME/.openclaw/agents/lumina/sessions"
+ARCHIVE_DIR="$SESSION_DIR/archive"
+MAX_SIZE_KB=200
+MAX_AGE_HOURS=24
+KEEP_RECENT=5
+
+log() { printf '[%s] %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "$1"; }
+
+# Cross-platform stat helpers
+_stat_mtime() {
+    if [[ "$OSTYPE" == "darwin"* ]]; then stat -f '%m' "$1"; else stat -c '%Y' "$1"; fi
+}
+_stat_size() {
+    if [[ "$OSTYPE" == "darwin"* ]]; then stat -f '%z' "$1"; else stat -c '%s' "$1"; fi
+}
+
+# Ensure directories exist
+if [ ! -d "$SESSION_DIR" ]; then
+    log "Session directory does not exist: $SESSION_DIR — nothing to do."
+    exit 0
+fi
+mkdir -p "$ARCHIVE_DIR"
+
+# Collect all .jsonl files (not in archive subdir), sorted newest-first
+# (macOS-compatible: avoid mapfile and find -printf)
+all_files=()
+while IFS= read -r f; do
+    [ -n "$f" ] && all_files+=("$f")
+done < <(
+    for f in "$SESSION_DIR"/*.jsonl; do
+        [ -f "$f" ] && echo "$(_stat_mtime "$f") $f"
+    done | sort -rn | awk '{print $2}'
+)
+
+total=${#all_files[@]}
+if [ "$total" -eq 0 ]; then
+    log "No .jsonl files found — nothing to do."
+    exit 0
+fi
+
+log "Found $total .jsonl file(s) in $SESSION_DIR"
+
+# The first KEEP_RECENT entries (newest) are protected
+archived=0
+for i in "${!all_files[@]}"; do
+    file="${all_files[$i]}"
+    basename_f="$(basename "$file")"
+
+    # Skip if already archived (shouldn't happen with maxdepth 1, but be safe)
+    if [ "$(dirname "$file")" = "$ARCHIVE_DIR" ]; then
+        continue
+    fi
+
+    # Protect the N most recent files
+    if [ "$i" -lt "$KEEP_RECENT" ]; then
+        log "KEEP (recent #$((i+1))): $basename_f"
+        continue
+    fi
+
+    # Check age (older than MAX_AGE_HOURS)
+    file_age_sec=$(( $(date +%s) - $(_stat_mtime "$file") ))
+    old_enough=$(( file_age_sec > MAX_AGE_HOURS * 3600 ))
+
+    # Check size (larger than MAX_SIZE_KB)
+    file_size_kb=$(( $(_stat_size "$file") / 1024 ))
+    big_enough=$(( file_size_kb >= MAX_SIZE_KB ))
+
+    if [ "$old_enough" -eq 1 ] || [ "$big_enough" -eq 1 ]; then
+        reason=""
+        [ "$old_enough" -eq 1 ] && reason="age=$(( file_age_sec / 3600 ))h"
+        [ "$big_enough" -eq 1 ] && { [ -n "$reason" ] && reason="$reason, "; reason="${reason}size=${file_size_kb}KB"; }
+        log "ARCHIVE ($reason): $basename_f"
+        mv -- "$file" "$ARCHIVE_DIR/$basename_f"
+        archived=$((archived + 1))
+    else
+        log "SKIP (below thresholds): $basename_f"
+    fi
+done
+
+log "Done. Archived $archived file(s)."