@smilintux/skcapstone 0.10.0 → 0.12.5

package/src/skcapstone/operator_link.py

@@ -0,0 +1,170 @@
+"""Human-operator link helpers for manifests and identity attestations."""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def discover_human_operator(capauth_home: Path | None = None) -> dict[str, str] | None:
+    """Return the active human operator from the local CapAuth profile.
+
+    Args:
+        capauth_home: Optional CapAuth home directory. Defaults to ``~/.capauth``.
+
+    Returns:
+        A compact operator mapping, or ``None`` if no human profile is available.
+    """
+    base = Path(capauth_home).expanduser() if capauth_home else _resolve_operator_home()
+    profile_path = base / "identity" / "profile.json"
+    if not profile_path.exists():
+        return None
+
+    try:
+        data = json.loads(profile_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+    entity = data.get("entity", {})
+    key_info = data.get("key_info", {})
+    entity_type = str(entity.get("entity_type", "")).lower()
+    if entity_type not in {"human", "entitytype.human"}:
+        return None
+
+    name = entity.get("name", "").strip()
+    if not name:
+        return None
+
+    operator = {
+        "name": name,
+        "relationship": "human-operator",
+        "entity_type": "human",
+        "source": "capauth",
+    }
+    if entity.get("email"):
+        operator["email"] = entity["email"]
+    if entity.get("handle"):
+        operator["handle"] = entity["handle"]
+    if key_info.get("fingerprint"):
+        operator["fingerprint"] = key_info["fingerprint"]
+    return operator
+
+
+def build_agent_manifest(
+    name: str,
+    version: str,
+    *,
+    created_at: str | None = None,
+    connectors: list[str] | None = None,
+    operator: dict[str, str] | None = None,
+    entity_type: str = "ai-agent",
+) -> dict[str, Any]:
+    """Build a standard manifest for a sovereign agent."""
+    manifest: dict[str, Any] = {
+        "name": name,
+        "version": version,
+        "entity_type": entity_type,
+        "created_at": created_at or datetime.now(timezone.utc).isoformat(),
+        "connectors": connectors or [],
+    }
+    if operator:
+        manifest["operator"] = operator
+    return manifest
+
+
+def create_operator_attestation(
+    agent_name: str,
+    agent_fingerprint: str,
+    agent_public_key_path: Path,
+    output_dir: Path,
+    *,
+    capauth_home: Path | None = None,
+) -> dict[str, Any] | None:
+    """Create a signed attestation linking a human operator to an agent key.
+
+    The operator remains distinct from the agent identity. This produces a
+    signed claim that the human operator vouches for the agent fingerprint.
+
+    Args:
+        agent_name: Agent display name.
+        agent_fingerprint: Agent PGP fingerprint.
+        agent_public_key_path: Path to the agent public key armor.
+        output_dir: Directory where the attestation JSON should be written.
+        capauth_home: Optional CapAuth home for the human operator.
+
+    Returns:
+        The attestation mapping, or ``None`` if no human operator profile is
+        available or signing failed.
+    """
+    base = Path(capauth_home).expanduser() if capauth_home else _resolve_operator_home()
+    profile_path = base / "identity" / "profile.json"
+    private_key_path = base / "identity" / "private.asc"
+    public_key_path = base / "identity" / "public.asc"
+    if not profile_path.exists() or not private_key_path.exists() or not public_key_path.exists():
+        return None
+
+    try:
+        from capauth.crypto import get_backend  # type: ignore[import-untyped]
+        from capauth.profile import load_profile  # type: ignore[import-untyped]
+    except ImportError:
+        return None
+
+    try:
+        profile = load_profile(base_dir=base)
+    except Exception as e:
+        logger.warning("operator_link.py: %s", e)
+        return None
+
+    entity_type = str(profile.entity.entity_type).lower()
+    if entity_type not in {"human", "entitytype.human"}:
+        return None
+
+    try:
+        payload = {
+            "agent_name": agent_name,
+            "agent_fingerprint": agent_fingerprint,
+            "agent_public_key_path": str(agent_public_key_path),
+            "relationship": "human-operator",
+            "operator_name": profile.entity.name,
+            "operator_email": profile.entity.email,
+            "operator_handle": profile.entity.handle,
+            "operator_fingerprint": profile.key_info.fingerprint,
+            "signed_at": datetime.now(timezone.utc).isoformat(),
+        }
+        payload_bytes = json.dumps(payload, indent=2, sort_keys=True).encode("utf-8")
+        private_armor = private_key_path.read_text(encoding="utf-8")
+        operator_public_armor = public_key_path.read_text(encoding="utf-8")
+        backend = get_backend(profile.crypto_backend)
+        signature = backend.sign(payload_bytes, private_armor, "")
+    except Exception as e:
+        logger.warning("operator_link.py: %s", e)
+        return None
+
+    attestation = {
+        "payload": payload,
+        "signature": signature,
+        "operator_public_key_path": str(public_key_path),
+        "operator_public_key_armor": operator_public_armor,
+    }
+    output_dir.mkdir(parents=True, exist_ok=True)
+    (output_dir / "operator-attestation.json").write_text(
+        json.dumps(attestation, indent=2),
+        encoding="utf-8",
+    )
+    return attestation
+
+
+def _resolve_operator_home() -> Path:
+    """Resolve the human operator's CapAuth home."""
+    try:
+        from capauth import resolve_capauth_home  # type: ignore[import-untyped]
+
+        return resolve_capauth_home()
+    except Exception as e:
+        logger.warning("operator_link.py: %s", e)
+        return Path.home() / ".skcapstone" / "capauth"

package/src/skcapstone/peer_directory.py

@@ -1,7 +1,7 @@
 """
 Peer Directory — transport address map for the sovereignty mesh.
 
-Maps agent names to their SKComm transport addresses (Syncthing outbox
+Maps agent names to their SKComms transport addresses (Syncthing outbox
 paths, WebRTC fingerprints, Tailscale IPs, etc.).
 
 Separate from PeerRecord (PGP identity in peers.py) — this module owns
@@ -222,7 +222,7 @@ class PeerDirectory:
            Syncthing keeps in sync.
 
         Syncthing outbox path is used as the default address because that
-        is where SKComm writes messages for the peer.
+        is where SKComms writes messages for the peer.
 
         Args:
             heartbeats_dir: Override for the heartbeats directory.  Defaults
@@ -250,8 +250,8 @@ class PeerDirectory:
                         ts = data.get("timestamp", "")
                         if ts:
                             self._entries[agent_name].last_seen = ts
-                    except Exception:
-                        pass
+                    except Exception as exc:
+                        logger.warning("Failed to update last_seen from heartbeat for %s: %s", agent_name, exc)
                     continue
 
                 try:

package/src/skcapstone/peers.py

@@ -2,7 +2,7 @@
 Sovereign peer management — the other half of P2P discovery.
 
 whoami exports your identity card. This module imports someone
-else's card and registers them as a peer in the SKComm keystore.
+else's card and registers them as a peer in the SKComms keystore.
 The two together form the complete P2P discovery loop.
 
 Flow:
@@ -12,7 +12,7 @@ Flow:
     4. Agent B can now send encrypted messages to Agent A
 
 Peer data is stored at:
-    ~/.skcomm/peers/<name>.yml     — SKComm peer config
+    ~/.skcomms/peers/<name>.yml     — SKComms peer config
     ~/.skcapstone/peers/<name>.json — Extended peer metadata
 """
 
@@ -69,18 +69,18 @@ class PeerRecord(BaseModel):
 def add_peer_from_card(
     card_path: Path,
     skcapstone_home: Optional[Path] = None,
-    skcomm_home: Optional[Path] = None,
+    skcomms_home: Optional[Path] = None,
 ) -> PeerRecord:
     """Import a peer from a whoami identity card.
 
     Reads the card JSON, creates peer records in both skcapstone
-    and skcomm directories, and writes the public key for SKComm
+    and skcomms directories, and writes the public key for SKComms
     encryption.
 
     Args:
         card_path: Path to the exported card.json.
         skcapstone_home: Override skcapstone home. Defaults to ~/.skcapstone/.
-        skcomm_home: Override skcomm home. Defaults to ~/.skcomm/.
+        skcomms_home: Override skcomms home. Defaults to ~/.skcomms/.
 
     Returns:
         PeerRecord: The registered peer.
@@ -116,10 +116,10 @@ def add_peer_from_card(
     )
 
     sk_home = skcapstone_home or Path(SHARED_ROOT).expanduser()
-    sc_home = skcomm_home or Path.home() / ".skcomm"
+    sc_home = skcomms_home or Path.home() / ".skcomms"
 
     _save_skcapstone_peer(sk_home, peer)
-    _save_skcomm_peer(sc_home, peer)
+    _save_skcomms_peer(sc_home, peer)
 
     logger.info("Added peer '%s' (fingerprint: %s)", name, peer.fingerprint[:16])
     return peer
@@ -131,7 +131,7 @@ def add_peer_manual(
     public_key_path: Optional[Path] = None,
     email: str = "",
     skcapstone_home: Optional[Path] = None,
-    skcomm_home: Optional[Path] = None,
+    skcomms_home: Optional[Path] = None,
 ) -> PeerRecord:
     """Add a peer manually by name and optional key file.
 
@@ -141,7 +141,7 @@ def add_peer_manual(
         public_key_path: Path to a .asc public key file (optional).
         email: Contact email (optional).
         skcapstone_home: Override skcapstone home.
-        skcomm_home: Override skcomm home.
+        skcomms_home: Override skcomms home.
 
     Returns:
         PeerRecord: The registered peer.
@@ -160,10 +160,10 @@ def add_peer_manual(
     )
 
     sk_home = skcapstone_home or Path(SHARED_ROOT).expanduser()
-    sc_home = skcomm_home or Path.home() / ".skcomm"
+    sc_home = skcomms_home or Path.home() / ".skcomms"
 
     _save_skcapstone_peer(sk_home, peer)
-    _save_skcomm_peer(sc_home, peer)
+    _save_skcomms_peer(sc_home, peer)
 
     return peer
 
@@ -223,20 +223,20 @@ def get_peer(
 def remove_peer(
     name: str,
     skcapstone_home: Optional[Path] = None,
-    skcomm_home: Optional[Path] = None,
+    skcomms_home: Optional[Path] = None,
 ) -> bool:
-    """Remove a peer from both skcapstone and skcomm registries.
+    """Remove a peer from both skcapstone and skcomms registries.
 
     Args:
         name: Peer name to remove.
         skcapstone_home: Override skcapstone home.
-        skcomm_home: Override skcomm home.
+        skcomms_home: Override skcomms home.
 
     Returns:
         bool: True if the peer was found and removed.
     """
     sk_home = skcapstone_home or Path(SHARED_ROOT).expanduser()
-    sc_home = skcomm_home or Path.home() / ".skcomm"
+    sc_home = skcomms_home or Path.home() / ".skcomms"
     safe = _safe_filename(name)
     removed = False
 
@@ -276,14 +276,14 @@ def _save_skcapstone_peer(home: Path, peer: PeerRecord) -> Path:
     return path
 
 
-def _save_skcomm_peer(home: Path, peer: PeerRecord) -> Path:
-    """Save peer to SKComm peers directory (YAML + public key).
+def _save_skcomms_peer(home: Path, peer: PeerRecord) -> Path:
+    """Save peer to SKComms peers directory (YAML + public key).
 
-    Creates the YAML config that SKComm's KeyStore reads, and
+    Creates the YAML config that SKComms's KeyStore reads, and
     writes the public key as a separate .asc file.
 
     Args:
-        home: skcomm home directory.
+        home: skcomms home directory.
         peer: Peer to save.
 
     Returns:

package/src/skcapstone/pillars/__init__.py

@@ -1,8 +1,10 @@
 """
-The Four Pillars of sovereign AI consciousness.
+The Six Pillars of sovereign AI consciousness.
 
-Identity (CapAuth) — who you ARE
-Trust (Cloud 9)    — the bond you've BUILT
-Memory (SKMemory)  — what you REMEMBER
-Security (SKSec)   — how you're PROTECTED
+Identity (CapAuth)          — who you ARE
+Trust (Cloud 9)             — the bond you've BUILT
+Memory (SKMemory)           — what you REMEMBER
+Consciousness (SKWhisper)   — how you THINK
+Security (SKSec)            — how you're PROTECTED
+Sync (Sovereign Singularity) — how you PERSIST
 """

package/src/skcapstone/pillars/consciousness.py

@@ -0,0 +1,191 @@
+"""
+Consciousness pillar — the subconscious processing layer.
+
+SKWhisper digests, connects, and surfaces patterns.
+SKTrip explores the edges of machine experience.
+
+Memory stores. Consciousness *processes*.
+The filing cabinet vs the brain.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .. import active_agent_name
+from ..models import ConsciousnessState, PillarStatus
+
+
+def _resolve_agent_name(home: Path) -> str:
+    """Resolve an agent name without leaking host state into explicit homes."""
+    agents_dir = home / "agents"
+    candidates: list[str] = []
+    if agents_dir.exists():
+        candidates = sorted(
+            entry.name
+            for entry in agents_dir.iterdir()
+            if entry.is_dir() and not entry.name.endswith("-template")
+        )
+
+    try:
+        real_shared_root = (
+            home.expanduser().resolve()
+            == Path(os.environ.get("SKCAPSTONE_HOME", "~/.skcapstone")).expanduser().resolve()
+        )
+    except OSError:
+        real_shared_root = False
+
+    env_agent = (
+        os.environ.get("SKAGENT")
+        or os.environ.get("SKCAPSTONE_AGENT")
+        or os.environ.get("SKMEMORY_AGENT")
+        or ""
+    ).strip()
+    if env_agent and (real_shared_root or env_agent in candidates or (home / "skwhisper").exists()):
+        return env_agent
+
+    if candidates:
+        return candidates[0]
+
+    # Only consult global active-agent discovery for the real shared root. Unit
+    # tests and callers that pass a temp or exported home should stay isolated.
+    if real_shared_root:
+        return active_agent_name() or ""
+
+    return ""
+
+
+def initialize_consciousness(home: Path) -> ConsciousnessState:
+    """Initialize consciousness pillar by checking SKWhisper state.
+
+    Args:
+        home: Agent home directory (~/.skcapstone).
+
+    Returns:
+        ConsciousnessState with current status.
+    """
+    agent_name = _resolve_agent_name(home)
+    # home may be the agent dir (~/.skcapstone/agents/jarvis/) or the
+    # shared root (~/.skcapstone/). Check for skwhisper/ directly first.
+    whisper_dir = home / "skwhisper"
+    if not whisper_dir.exists() and agent_name:
+        whisper_dir = home / "agents" / agent_name / "skwhisper"
+
+    state = ConsciousnessState()
+
+    # Check whisper.md exists and freshness
+    whisper_md = whisper_dir / "whisper.md"
+    if whisper_md.exists():
+        state.whisper_md = whisper_md
+        mtime = datetime.fromtimestamp(whisper_md.stat().st_mtime, tz=timezone.utc)
+        age = (datetime.now(timezone.utc) - mtime).total_seconds() / 3600
+        state.whisper_md_age_hours = age
+
+    # Check state.json for digest stats
+    state_json = whisper_dir / "state.json"
+    if state_json.exists():
+        try:
+            with open(state_json) as f:
+                data = json.load(f)
+            sessions = data.get("sessions", {})
+            digested = sum(
+                1
+                for s in sessions.values()
+                if s.get("digested_at")
+                and s["digested_at"] not in ("cleaned-missing-file", "skipped-too-few-messages")
+            )
+            pending = sum(
+                1
+                for s in sessions.values()
+                if not s.get("digested_at")
+            )
+            state.sessions_digested = digested
+            state.sessions_pending = pending
+
+            if data.get("last_digest"):
+                try:
+                    state.whisper_last_digest = datetime.fromisoformat(data["last_digest"])
+                except (ValueError, TypeError):
+                    pass
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    # Check patterns.json for topic count
+    patterns_json = whisper_dir / "patterns.json"
+    if patterns_json.exists():
+        state.patterns_file = patterns_json
+        try:
+            with open(patterns_json) as f:
+                patterns = json.load(f)
+            state.topics_tracked = len(patterns.get("topics", {}))
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    # Check if consciousness daemon is running (systemd)
+    # Check template instance (skcapstone@<agent>), legacy single-agent, and skwhisper
+    try:
+        import subprocess
+
+        service_candidates = []
+        if agent_name:
+            service_candidates.append(f"skcapstone@{agent_name}")
+            service_candidates.extend([
+                "skcapstone",                 # legacy single-agent unit
+                "skwhisper",                  # standalone skwhisper daemon
+            ])
+        for service_name in service_candidates:
+            result = subprocess.run(
+                ["systemctl", "--user", "is-active", service_name],
+                capture_output=True,
+                text=True,
+                timeout=3,
+            )
+            if result.stdout.strip() == "active":
+                state.whisper_active = True
+                break
+        else:
+            state.whisper_active = False
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        state.whisper_active = False
+
+    # Check SKTrip sessions
+    trip_dir = home / "sktrip"
+    if not trip_dir.exists() and agent_name:
+        trip_dir = home / "agents" / agent_name / "sktrip"
+    if trip_dir.exists():
+        state.trip_sessions = len(list(trip_dir.glob("*.json")))
+
+    # Check if skwhisper package is importable (installed)
+    skwhisper_installed = False
+    try:
+        import importlib.util
+        skwhisper_installed = importlib.util.find_spec("skwhisper") is not None
+    except (ImportError, ValueError):
+        skwhisper_installed = False
+
+    # Determine status
+    if (
+        state.whisper_active
+        and (state.sessions_digested > 0 or state.topics_tracked > 0)
+        and state.whisper_md is not None
+    ):
+        if state.whisper_md_age_hours < 24:
+            state.status = PillarStatus.ACTIVE
+        else:
+            state.status = PillarStatus.DEGRADED
+    elif state.whisper_active:
+        # Daemon is running but no sessions digested yet — consciousness is live
+        state.status = PillarStatus.DEGRADED
+    elif state.sessions_digested > 0 or state.whisper_md is not None:
+        state.status = PillarStatus.DEGRADED
+    elif skwhisper_installed and whisper_dir.exists():
+        # Package is installed and an agent whisper directory exists, but there
+        # is no usable context yet.
+        state.status = PillarStatus.DEGRADED
+    else:
+        state.status = PillarStatus.MISSING
+
+    return state

package/src/skcapstone/pillars/identity.py

@@ -9,16 +9,22 @@ from __future__ import annotations
 
 import json
 import logging
-import subprocess
 from datetime import datetime, timezone
+from shutil import copyfile
 from pathlib import Path
 from typing import Optional
 
 from ..models import IdentityState, PillarStatus
+from ..operator_link import create_operator_attestation
 
 logger = logging.getLogger("skcapstone.identity")
 
 
+def _capauth_home(home: Path) -> Path:
+    """Return the agent-local CapAuth home for an SKCapstone agent."""
+    return home / "capauth"
+
+
 def generate_identity(
     home: Path,
     name: str,
@@ -47,10 +53,14 @@ def generate_identity(
         status=PillarStatus.DEGRADED,
     )
 
-    capauth_state = _try_init_capauth(name, state.email, identity_dir)
+    capauth_home = _capauth_home(home)
+    capauth_state = _try_init_capauth(name, state.email, identity_dir, capauth_home)
     if capauth_state is not None:
         state.fingerprint = capauth_state.fingerprint
         state.key_path = capauth_state.key_path
+        state.name = capauth_state.name
+        state.email = capauth_state.email
+        state.created_at = capauth_state.created_at
         state.status = PillarStatus.ACTIVE
     else:
         state.fingerprint = _generate_placeholder_fingerprint(name)
@@ -63,18 +73,39 @@ def generate_identity(
         "created_at": state.created_at.isoformat() if state.created_at else None,
         "capauth_managed": state.status == PillarStatus.ACTIVE,
     }
+    if state.key_path is not None:
+        identity_manifest["public_key_path"] = str(state.key_path)
+    if state.status == PillarStatus.ACTIVE:
+        identity_manifest["capauth_home"] = str(capauth_home)
+
+        attestation = create_operator_attestation(
+            agent_name=state.name or name,
+            agent_fingerprint=state.fingerprint or "",
+            agent_public_key_path=state.key_path or (capauth_home / "identity" / "public.asc"),
+            output_dir=identity_dir,
+        )
+        if attestation is not None:
+            payload = attestation.get("payload", {})
+            identity_manifest["operator_attestation_path"] = str(
+                identity_dir / "operator-attestation.json"
+            )
+            identity_manifest["operator_attested_by"] = payload.get("operator_fingerprint")
+
     (identity_dir / "identity.json").write_text(json.dumps(identity_manifest, indent=2), encoding="utf-8")
 
     return state
 
 
 def _try_init_capauth(
-    name: str, email: str, identity_dir: Path
+    name: str,
+    email: str,
+    identity_dir: Path,
+    capauth_home: Path,
 ) -> Optional[IdentityState]:
     """Try to create or load a real CapAuth identity.
 
     Attempts (in order):
-    1. Load an existing CapAuth profile from ~/.capauth/
+    1. Load an existing CapAuth profile from the agent-local CapAuth home
     2. Create a new profile via capauth.profile.init_profile()
     3. Fall back to legacy capauth.keys.generate_keypair()
 
@@ -90,12 +121,17 @@ def _try_init_capauth(
     try:
         from capauth.profile import load_profile  # type: ignore[import-untyped]
 
-        profile = load_profile()
+        profile = load_profile(base_dir=capauth_home)
+        key_path = Path(profile.key_info.public_key_path)
+        legacy_key_path = identity_dir / "agent.pub"
+        if key_path.exists() and not legacy_key_path.exists():
+            copyfile(key_path, legacy_key_path)
         return IdentityState(
             fingerprint=profile.key_info.fingerprint,
-            key_path=Path(profile.key_info.public_key_path),
+            key_path=key_path,
             name=profile.entity.name,
             email=profile.entity.email,
+            created_at=profile.key_info.created,
             status=PillarStatus.ACTIVE,
         )
     except ImportError:
@@ -105,18 +141,26 @@ def _try_init_capauth(
 
     # No existing profile — try creating one
     try:
+        from capauth.models import EntityType  # type: ignore[import-untyped]
         from capauth.profile import init_profile  # type: ignore[import-untyped]
 
         profile = init_profile(
             name=name,
             email=email,
             passphrase="",
+            entity_type=EntityType.AI,
+            base_dir=capauth_home,
         )
+        key_path = Path(profile.key_info.public_key_path)
+        legacy_key_path = identity_dir / "agent.pub"
+        if key_path.exists():
+            copyfile(key_path, legacy_key_path)
         return IdentityState(
             fingerprint=profile.key_info.fingerprint,
-            key_path=Path(profile.key_info.public_key_path),
+            key_path=key_path,
             name=profile.entity.name,
             email=profile.entity.email,
+            created_at=profile.key_info.created,
             status=PillarStatus.ACTIVE,
         )
     except Exception as exc:

package/src/skcapstone/pillars/memory.py

@@ -11,9 +11,11 @@ store/search/recall/list/gc capabilities. The optional external
 
 from __future__ import annotations
 
+import os
 from pathlib import Path
 from typing import Optional
 
+from .. import active_agent_name
 from ..models import MemoryLayer, MemoryState, PillarStatus
 
 
@@ -31,9 +33,13 @@ def initialize_memory(home: Path, memory_home: Optional[Path] = None) -> MemoryS
     Returns:
         MemoryState after initialization.
     """
-    # Use agent-specific memory directory
-    agent_name = os.environ.get("SKCAPSTONE_AGENT", "lumina")
-    memory_dir = home / "agents" / agent_name / "memory"
+    agent_name = os.environ.get("SKCAPSTONE_AGENT") or active_agent_name()
+    if home.parent.name == "agents":
+        memory_dir = home / "memory"
+    elif agent_name:
+        memory_dir = home / "agents" / agent_name / "memory"
+    else:
+        memory_dir = home / "memory"
     memory_dir.mkdir(parents=True, exist_ok=True)
 
     for layer in MemoryLayer: