apsimo 1.3.0__py3-none-any.whl

apsimo/harness_integration/__init__.py

@@ -0,0 +1,45 @@
+"""Harness integration - writes context files and skills to each harness.
+
+This module provides automatic integration with:
+- Crush (MCP + skill)
+- Codex (MCP + skill)
+- Claude Code (MCP + skill)
+- OpenCode (MCP + skill)
+- Hermes (plugin only)
+"""
+
+from .context import (
+    write_apsimo_context,
+    APSIMO_CONTEXT_TEMPLATE,
+    write_colony_context,
+    COLONY_CONTEXT_TEMPLATE,
+)
+from .skills import (
+    write_apsimo_skill,
+    write_apsimo_check_skill,
+    remove_apsimo_skill,
+    APSIMO_DIAGNOSTIC_SKILL,
+    APSIMO_CHECK_SKILL,
+    write_colony_skill,
+    write_colony_check_skill,
+    remove_colony_skill,
+    get_skill_path,
+    get_skill_config_path,
+    COLONY_DIAGNOSTIC_SKILL,
+    COLONY_CHECK_SKILL,
+)
+
+__all__ = [
+    "write_apsimo_context", "write_apsimo_skill", "write_apsimo_check_skill",
+    "remove_apsimo_skill", "APSIMO_CONTEXT_TEMPLATE",
+    "APSIMO_DIAGNOSTIC_SKILL", "APSIMO_CHECK_SKILL",
+    "write_colony_context",
+    "write_colony_skill",
+    "write_colony_check_skill",
+    "remove_colony_skill",
+    "get_skill_path",
+    "get_skill_config_path",
+    "COLONY_CONTEXT_TEMPLATE",
+    "COLONY_DIAGNOSTIC_SKILL",
+    "COLONY_CHECK_SKILL",
+]

apsimo/harness_integration/context.py

@@ -0,0 +1,41 @@
+"""Write a short, model-independent Apsimo reference into a workspace."""
+from pathlib import Path
+
+APSIMO_CONTEXT_TEMPLATE = """# Apsimo integration
+
+Apsimo is the cognition and continuity layer, formerly ColonyAI. Your agent's
+private identity is separate from the platform name. Old-name searches refer to
+the same platform and history.
+
+Use `apsimo_health` to check connectivity and `apsimo_get_context` for relevant,
+authenticated context. Check `apsimo_check_commitments` before promising work.
+Recall useful evidence with `apsimo_lookup_facts`; cite the returned source and
+ask about contradictions. Save durable facts with `apsimo_remember_fact` only
+when their source and usefulness are clear. Corrections and forgetting govern
+source-backed recall across sessions; do not create diagnostic junk memories.
+
+Use `apsimo doctor` and `apsimo mcp detect` for installation checks. Hermes uses
+its native Apsimo plugin and memory provider. Coding harnesses may use the MCP
+server. Both connect to the same selected instance over its authenticated API;
+sharing an instance does not grant every caller access to every private source.
+
+APSIMO_* configuration names are preferred; existing COLONY_* names remain
+accepted. Use the selected instance's actual configuration and credential
+reference. Never guess a key or print credentials into diagnostic transcripts.
+"""
+
+# Public compatibility aliases point to the same template and writer.
+COLONY_CONTEXT_TEMPLATE = APSIMO_CONTEXT_TEMPLATE
+
+
+def write_apsimo_context(workspace_dir: Path) -> bool:
+    if not workspace_dir.exists():
+        return False
+    try:
+        (workspace_dir / "APSIMO.md").write_text(APSIMO_CONTEXT_TEMPLATE)
+        return True
+    except OSError:
+        return False
+
+
+write_colony_context = write_apsimo_context

apsimo/harness_integration/skills.py

@@ -0,0 +1,231 @@
+"""Write Apsimo diagnostic skill to harness skills directories."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+
+# Skill directory paths for each harness
+SKILL_PATHS = {
+    "openclaw": None,  # Special case - uses workspace_dir
+    "crush": "~/.config/crush/skills/apsimo-diagnose",
+    "codex": "~/.codex/skills/apsimo-diagnose",
+    "claude-code": "~/.codex/skills/apsimo-diagnose",  # Shares with Codex
+    "opencode": "~/.config/opencode/skills/apsimo-diagnose",
+    "hermes": None,  # Plugin-based, no skill directory
+}
+
+# Config paths for skills_paths updates (Crush only)
+CONFIG_PATHS = {
+    "crush": ["~/.crush.json", "~/.config/crush/crush.json"],
+}
+
+
+APSIMO_DIAGNOSTIC_SKILL = """---
+name: apsimo-diagnose
+description: Diagnose Apsimo or legacy ColonyAI connection failures and missing recalled context using the selected instance.
+---
+
+# Apsimo diagnostics
+
+1. Run `apsimo status` and `apsimo doctor`. Read the reported endpoint and instance
+   instead of assuming a directory, machine, port, or database backend.
+2. For coding harnesses, run `apsimo mcp detect`. Confirm one `apsimo` MCP server
+   is configured. Legacy `colony` entries are migrated by `apsimo mcp setup --harness <name>`.
+3. Call `apsimo_health`. If it fails, report the actual transport or authentication
+   error. Use the selected instance's credential reference; never guess a key,
+   print its value, or dump a whole configuration into a transcript.
+4. If health passes, use `apsimo_get_context` for the authenticated contact and
+   `apsimo_lookup_facts` for a known source-backed fact. Report what was actually
+   retrieved. Do not insert test facts into ordinary memory.
+5. For Hermes, inspect its selected profile's plugin and memory-provider status.
+   Correct the indicated connection or configuration, then repeat the failed
+   probe once. A successful HTTP request alone does not prove useful recollection.
+
+Apsimo is the platform's new name; Aeva or another private agent keeps its own
+identity. Existing state paths and COLONY_* variables remain supported. Conflicting
+explicit APSIMO_* and COLONY_* settings must be resolved at configuration load.
+"""
+COLONY_DIAGNOSTIC_SKILL = APSIMO_DIAGNOSTIC_SKILL
+
+
+def get_skill_path(harness_id: str) -> Path | None:
+    """Get the skill directory path for a harness.
+    
+    Args:
+        harness_id: Harness identifier (e.g., 'crush', 'openclaw')
+    
+    Returns:
+        Path to skill directory, or None if harness doesn't support skills
+    """
+    path_str = SKILL_PATHS.get(harness_id)
+    if path_str:
+        canonical = Path(path_str).expanduser()
+        legacy = canonical.with_name("colony-diagnose")
+        # Reuse an installed legacy directory, so setup does not discover two
+        # copies of one skill. New installations use the canonical directory.
+        return legacy if legacy.exists() and not canonical.exists() else canonical
+    return None
+
+
+def get_skill_config_path(harness_id: str) -> Path | None:
+    """Get the harness config path for skills_paths update.
+    
+    Args:
+        harness_id: Harness identifier
+    
+    Returns:
+        Path to config file, or None if not applicable
+    """
+    config_paths = CONFIG_PATHS.get(harness_id, [])
+    for path_str in config_paths:
+        path = Path(path_str).expanduser()
+        if path.exists():
+            return path
+    return None
+
+
+def write_apsimo_skill(harness_id: str, workspace_dir: Path | None = None) -> bool:
+    """Write Apsimo diagnostic skill to harness skills directory.
+    
+    For Crush: also updates options.skills_paths in config.
+    
+    Args:
+        harness_id: Harness identifier (e.g., 'crush', 'openclaw')
+        workspace_dir: Optional workspace dir (used for OpenClaw to override)
+    
+    Returns:
+        True if written successfully, False otherwise (including if harness doesn't support skills)
+    """
+    # Special handling for OpenClaw - use workspace skills dir
+    if harness_id == "openclaw" and workspace_dir:
+        skill_dir = workspace_dir / "skills" / "apsimo-diagnose"
+    else:
+        skill_dir = get_skill_path(harness_id)
+    
+    # Harness doesn't support skills (e.g., Hermes)
+    if not skill_dir:
+        return False
+    
+    try:
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        skill_md = skill_dir / "SKILL.md"
+        skill_md.write_text(COLONY_DIAGNOSTIC_SKILL)
+        
+        # For Crush, update skills_paths in config
+        if harness_id == "crush":
+            _update_crush_skills_paths()
+        
+        return True
+    except Exception:
+        return False
+
+
+def remove_apsimo_skill(harness_id: str) -> bool:
+    """Remove Apsimo diagnostic skill from harness skills directory.
+    
+    Args:
+        harness_id: Harness identifier
+    
+    Returns:
+        True if removed successfully, False if not found or error
+    """
+    skill_dir = get_skill_path(harness_id)
+    
+    if not skill_dir or not skill_dir.exists():
+        return False
+    
+    try:
+        shutil.rmtree(skill_dir)
+        return True
+    except Exception:
+        return False
+
+
+def _update_crush_skills_paths() -> bool:
+    """Internal: Add ~/.config/crush/skills to Crush's skills_paths if not present.
+    
+    Crush config can be at:
+    1. ~/.crush.json (checked first by Crush)
+    2. ~/.config/crush/crush.json (checked second)
+    
+    We check both and update whichever exists, preferring ~/.crush.json.
+    If neither exists, we don't create one just for skills_paths.
+    """
+    skill_path_to_add = "~/.config/crush/skills"
+    
+    # Find existing config
+    config_path = get_skill_config_path("crush")
+    if not config_path:
+        return False  # No config exists, don't create one
+    
+    try:
+        data = json.loads(config_path.read_text())
+    except (json.JSONDecodeError, FileNotFoundError):
+        return False
+    
+    # Check if skills_paths already includes our path
+    options = data.get("options", {})
+    skills_paths = options.get("skills_paths", [])
+    
+    # Normalize paths for comparison
+    normalized_new = str(Path(skill_path_to_add).expanduser())
+    normalized_existing = [str(Path(p).expanduser()) for p in skills_paths]
+    
+    if normalized_new in normalized_existing:
+        return True  # Already present
+    
+    # Add the path
+    skills_paths.append(skill_path_to_add)
+    options["skills_paths"] = skills_paths
+    data["options"] = options
+    
+    try:
+        config_path.write_text(json.dumps(data, indent=2))
+        return True
+    except Exception:
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Apsimo Check Skill (for on-demand initiative checking)
+# ---------------------------------------------------------------------------
+
+APSIMO_CHECK_SKILL = """---
+name: apsimo-check
+description: Review current commitments and useful work through the selected Apsimo instance.
+---
+
+Use `apsimo_get_context` and `apsimo_check_commitments` for the authenticated
+contact. Summarize overdue work, current commitments, and source-backed surprises.
+Distinguish observations from proposed actions. Respect existing task ownership
+and execution limits; do not create duplicate work or claim that a task ran
+without its execution evidence. Do not write a memory merely because this check
+was performed. If a tool fails, report its actual blocker and change strategy.
+"""
+COLONY_CHECK_SKILL = APSIMO_CHECK_SKILL
+
+
+def write_apsimo_check_skill(workspace_dir: Path) -> bool:
+    """Write apsimo-check skill to OpenClaw workspace skills directory.
+
+    Args:
+        workspace_dir: OpenClaw workspace directory
+
+    Returns:
+        True if written successfully, False otherwise
+    """
+    skill_dir = workspace_dir / "skills" / "apsimo-check"
+    try:
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        (skill_dir / "SKILL.md").write_text(COLONY_CHECK_SKILL)
+        return True
+    except Exception:
+        return False
+
+
+write_colony_skill = write_apsimo_skill
+write_colony_check_skill = write_apsimo_check_skill
+remove_colony_skill = remove_apsimo_skill

apsimo/identity/__init__.py

@@ -0,0 +1,26 @@
+"""Identity normalization service (v0.16.0).
+
+Maps between the identifier formats Colony uses for a person:
+contact-store CID, Neo4j Person node ID, display name, and platform
+handles (email, phone, etc.).
+"""
+
+from apsimo.identity.resolver import (
+    IdentityResolver,
+    OwnerIdentityError,
+    get_identity_resolver,
+    get_owner_contact_id,
+    get_owner_name,
+    get_persona_name,
+    reset_identity_resolver,
+)
+
+__all__ = [
+    "IdentityResolver",
+    "OwnerIdentityError",
+    "get_identity_resolver",
+    "get_owner_contact_id",
+    "get_owner_name",
+    "get_persona_name",
+    "reset_identity_resolver",
+]

apsimo/identity/participants.py

@@ -0,0 +1,181 @@
+"""ParticipantResolver -- per-message sender -> contact attribution.
+
+The attribution chokepoint for relationship intelligence (docs/RELATIONSHIPS.md):
+every synced turn that carries a ``sender`` resolves to a real contact here,
+server-side, regardless of client caching. Unknown people become shadow
+contacts so history accrues from first contact; machines resolve to the
+reserved ``system`` sentinel and never touch relationship stores.
+
+Resolution ladder (first hit wins):
+  1. exact / cross-gateway messaging handle (phones unify across sms/rcs/
+     whatsapp/signal/imessage via phone_key; emails normalize)
+  2. scoped display-name: propose a candidate association, without attributing
+     the sender to that person's identity or private history
+  3. shadow contact (tier unknown, interaction_allowed=false, provenance
+     recorded), when COLONY_IDENTITY_SHADOW_CONTACTS (default true)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+#: Reserved contact id for machine-origin turns. Comms may record it for ops
+#: visibility; ToM/interactions/relationship surfaces must always exclude it.
+SYSTEM_CONTACT_ID = "system"
+
+
+def shadow_contacts_enabled() -> bool:
+    return os.environ.get(
+        "COLONY_IDENTITY_SHADOW_CONTACTS", "true").strip().lower() != "false"
+
+
+def machine_channel_prefixes() -> tuple:
+    raw = os.environ.get("COLONY_IDENTITY_MACHINE_CHANNELS", "cron,api,internal")
+    return tuple(p.strip().lower() for p in raw.split(",") if p.strip())
+
+
+def is_machine_turn(channel_id: str, user_text: str, has_sender: bool) -> bool:
+    """A turn is machine-origin when it has no human sender AND either rides
+    a machine channel or carries system-origin text markers. A turn WITH a
+    resolved human sender is never reclassified (a human talking on an api
+    channel is still a human)."""
+    if has_sender:
+        return False
+    ch = (channel_id or "").strip().lower()
+    for prefix in machine_channel_prefixes():
+        if ch == prefix or ch.startswith(prefix + ":"):
+            return True
+    try:
+        from apsimo.delivery.reachout_policy import is_system_origin
+        if is_system_origin(user_text):
+            return True
+    except ImportError:
+        pass
+    return False
+
+
+@dataclass
+class Resolution:
+    contact_id: Optional[str]
+    method: str          # handle | scoped_name | shadow | none
+    created: bool = False
+    proposal_filed: bool = False
+    candidate_contact_id: Optional[str] = None
+    proposal_id: Optional[str] = None
+
+
+class ParticipantResolver:
+    def __init__(self, contacts_store: Any) -> None:
+        self._store = contacts_store
+
+    async def resolve(self, *, platform: str, user_id: str,
+                      display_name: str = "", group_id: str = "",
+                      channel_id: str = "") -> Resolution:
+        """Resolve a sender to a contact id (see module doc for the ladder)."""
+        platform = (platform or "").strip().lower()
+        user_id = (user_id or "").strip()
+        if not user_id:
+            return Resolution(None, "none")
+
+        # 0. Already-canonical contact id (e.g. the voice channel, where the
+        # speaker was resolved to a contact upstream and passed as user_id).
+        # Confirm it exists rather than minting a shadow for it.
+        if user_id.startswith("cid-"):
+            try:
+                if await self._store.get(user_id) is not None:
+                    return Resolution(user_id, "contact_id")
+            except Exception:
+                pass
+
+        # 1. Handle match (exact + cross-gateway phone + email normalization).
+        try:
+            c = await self._store.resolve_messaging_handle(platform, user_id)
+        except Exception:
+            logger.debug("participant handle resolve failed", exc_info=True)
+            c = None
+        if c is not None:
+            return Resolution(c.contact_id, "handle")
+
+        # 2. A name can suggest a link; it cannot establish attribution.
+        candidate, proposal = None, None
+        if display_name and group_id:
+            match = await self._scoped_name_match(platform, group_id, display_name)
+            if match is not None:
+                proposal = await self._file_handle_proposal(
+                    match, platform, user_id, display_name)
+                candidate = match
+
+        # 3. Shadow contact.
+        if not shadow_contacts_enabled():
+            return Resolution(None, "none", proposal_filed=bool(proposal),
+                              candidate_contact_id=candidate, proposal_id=proposal)
+        try:
+            contact = await self._store.create(
+                display_name=display_name or user_id,
+                trust_tier="unknown",
+                interaction_allowed=False,
+                import_source="auto:sender",
+                notes=(f"Auto-created from first contact on {channel_id or platform}"
+                       + (f" (group {group_id})" if group_id else "")),
+            )
+            await self._store.add_handle(
+                contact.contact_id, platform, user_id,
+                is_primary=True, confidence=0.9, source="auto:sender")
+            logger.info("Shadow contact %s created for %s:%s (%r)",
+                        contact.contact_id, platform, user_id,
+                        display_name or "?")
+            return Resolution(contact.contact_id, "shadow", created=True,
+                              proposal_filed=bool(proposal), candidate_contact_id=candidate,
+                              proposal_id=proposal)
+        except Exception:
+            logger.warning("shadow contact creation failed for %s:%s",
+                           platform, user_id, exc_info=True)
+            return Resolution(None, "none")
+
+    # -- rung 2 helpers ----------------------------------------------------
+    async def _scoped_name_match(self, platform: str, group_id: str,
+                                 display_name: str) -> Optional[str]:
+        """The display name matches exactly ONE member of this group's scope."""
+        try:
+            scope = await self._store.get_scope(
+                platform=platform, external_id=str(group_id))
+            if scope is None:
+                return None
+            members = await self._store.scope_members(scope.scope_id)
+        except Exception:
+            return None
+        hits = []
+        want = display_name.strip().lower()
+        for m in members or []:
+            cid = getattr(m, "contact_id", None) or (
+                m.get("contact_id") if isinstance(m, dict) else None)
+            if not cid:
+                continue
+            try:
+                c = await self._store.get(cid)
+            except Exception:
+                continue
+            if c is None:
+                continue
+            names = {str(c.display_name or "").strip().lower(),
+                     str(getattr(c, "given_name", "") or "").strip().lower()}
+            if want and (want in names
+                         or any(n and want.split()[0] == n.split()[0]
+                                for n in names if n)):
+                hits.append(c.contact_id)
+        return hits[0] if len(hits) == 1 else None
+
+    async def _file_handle_proposal(self, contact_id: str, platform: str,
+                                    user_id: str, display_name: str) -> Optional[str]:
+        """Keep the hypothesis outside the handle index used for attribution."""
+        try:
+            result = await self._store.propose_handle_link(contact_id, platform, user_id)
+            return result['candidate_id'] if result['status'] == 'pending' else None
+        except Exception:
+            logger.debug("handle proposal failed", exc_info=True)
+            return None