apsimo 1.3.0__py3-none-any.whl

apsimo/directives/models.py

@@ -0,0 +1,206 @@
+"""Directive / boundary data model.
+
+A Directive is a durable standing instruction from the owner, captured from
+conversation or set explicitly. It has a polarity:
+
+* PROHIBIT -- "don't / avoid / ignore / stop / leave alone X". A binding
+  boundary: autonomous actions that match it are REFUSED.
+* REQUIRE  -- "always / make sure to / from now on do X". A standing
+  obligation surfaced to the reasoner and the initiative layer.
+* PREFER   -- a soft preference (context only, never blocks).
+
+Directives are deployment-agnostic: the subject text and match terms come
+from the owner's own words / config, never hardcoded here.
+"""
+
+from __future__ import annotations
+
+import re
+import json
+import time
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class Polarity(str, Enum):
+    PROHIBIT = "prohibit"
+    REQUIRE = "require"
+    PREFER = "prefer"
+
+
+# Marker term for the one-command global pause (Amendment 1.5). A PROHIBIT
+# directive carrying this term refuses EVERY act-capability action while
+# active. It never matches by keyword (leading underscores keep it out of
+# normalize_terms output), so only the explicit kill switch can set it.
+GLOBAL_PAUSE_TERM = "__all_autonomy__"
+
+
+class Level(str, Enum):
+    """How deep a PROHIBIT boundary cuts.
+
+    Boundaries bind ACTION, not judgment or perception, except when the
+    boundary is explicitly about perception (privacy). Ignorance-based safety
+    is brittle: perception and learning stay maximally broad while action is
+    gated.
+
+    ACT (default): blocks mutations, delegated tasks, and autonomous outbound
+        actions about the subject. Reads, awareness, reflection, and answering
+        the owner's direct questions remain OPEN.
+    OBSERVE: full blackout -- blocks reads/perception too. Chosen only when
+        the owner uses explicit perception language ("don't look at / don't
+        read / stay out of / don't monitor").
+    """
+    ACT = "act"
+    OBSERVE = "observe"
+
+
+def default_level() -> "Level":
+    """Config knob: what an unqualified prohibition means (default act)."""
+    import os
+    raw = os.environ.get("COLONY_BOUNDARY_DEFAULT_LEVEL", "act").strip().lower()
+    try:
+        return Level(raw)
+    except ValueError:
+        return Level.ACT
+
+
+# Explicit perception language -> OBSERVE (full blackout).
+PERCEPTION_RE = re.compile(
+    r"\b(?:look(?:ing)?\s+at|read(?:ing)?(?!-only\b)|watch(?:ing)?|monitor(?:ing)?|"
+    r"track(?:ing)?|stay\s+out\s+of|snoop|peek|observe|observing|"
+    r"even\s+look)\b", re.IGNORECASE,
+)
+
+
+def level_from_text(text: Optional[str]) -> "Level":
+    """Derive the boundary level from the owner's phrasing."""
+    if text and PERCEPTION_RE.search(str(text)):
+        return Level.OBSERVE
+    return default_level()
+
+
+class DirectiveStatus(str, Enum):
+    ACTIVE = "active"
+    REVOKED = "revoked"
+    EXPIRED = "expired"
+    SUPERSEDED = "superseded"
+
+
+# Generic tokens that carry no discriminating meaning for subject matching.
+_STOPWORDS = frozenset({
+    "the", "a", "an", "to", "of", "on", "in", "for", "with", "about", "at",
+    "my", "your", "me", "you", "it", "that", "this", "any", "some", "and",
+    "or", "please", "just", "really", "anymore", "again", "do", "not", "dont",
+    "don", "ever", "stop", "avoid", "ignore", "never", "leave", "alone",
+    "touch", "is", "are", "be", "when", "if", "should", "would", "can",
+    # generic filler verbs / quantifiers that carry no subject meaning
+    "track", "tracking", "anything", "everything", "something", "stuff",
+    "thing", "things", "worry", "worrying", "bother", "bothering", "mention",
+    "mentioning", "care", "dealing", "deal", "regarding", "worried",
+})
+
+_WORD = re.compile(r"[a-z0-9][a-z0-9_+.\-/]*")
+
+
+def normalize_terms(text: Optional[str]) -> List[str]:
+    """Lowercase significant tokens from a subject/target string."""
+    if not text:
+        return []
+    toks = _WORD.findall(str(text).lower())
+    return [t for t in toks if t not in _STOPWORDS and len(t) > 1]
+
+
+@dataclass
+class Directive:
+    """A standing owner directive / boundary."""
+
+    subject: str                     # human-readable subject ("repo colony-web")
+    polarity: Polarity = Polarity.PROHIBIT
+    raw_text: str = ""               # the owner's original words
+    match_terms: List[str] = field(default_factory=list)   # normalized subject tokens
+    entity_ids: List[str] = field(default_factory=list)    # optional graph entity ids
+    action_kinds: List[str] = field(default_factory=list)  # limit to kinds; empty = all
+    source: str = "owner_explicit"   # owner_explicit | inferred | config
+    confidence: float = 0.9
+    status: DirectiveStatus = DirectiveStatus.ACTIVE
+    level: Optional[Level] = None    # act | observe (PROHIBIT only; None -> derive)
+    id: str = field(default_factory=lambda: f"dir-{uuid.uuid4().hex[:12]}")
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+    expires_at: Optional[float] = None
+    evidence: Optional[Dict[str, Any]] = None
+
+    def __post_init__(self) -> None:
+        if isinstance(self.polarity, str):
+            self.polarity = Polarity(self.polarity)
+        if isinstance(self.status, str):
+            self.status = DirectiveStatus(self.status)
+        if isinstance(self.level, str):
+            self.level = Level(self.level)
+        if self.level is None:
+            # Conservative migration/default: derive from phrasing; only
+            # perception-explicit wording escalates to a full blackout.
+            self.level = level_from_text(self.raw_text or self.subject)
+        if not self.match_terms:
+            self.match_terms = normalize_terms(self.subject)
+
+    def is_active(self, now: Optional[float] = None) -> bool:
+        if self.status != DirectiveStatus.ACTIVE:
+            return False
+        if self.expires_at is not None and (now or time.time()) > self.expires_at:
+            return False
+        return True
+
+    def to_row(self) -> Dict[str, Any]:
+        row = {
+            "id": self.id,
+            "subject": self.subject,
+            "polarity": self.polarity.value,
+            "raw_text": self.raw_text,
+            "match_terms": " ".join(self.match_terms),
+            "entity_ids": " ".join(self.entity_ids),
+            "action_kinds": " ".join(self.action_kinds),
+            "source": self.source,
+            "confidence": self.confidence,
+            "status": self.status.value,
+            "level": self.level.value if self.level else "act",
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "expires_at": self.expires_at,
+        }
+
+        if self.evidence is not None:
+            # Existing metadata column, no second prose copy or schema. Older
+            # readers see an empty subject rather than resurrecting erased text.
+            row.update(subject='', raw_text='', match_terms='',
+                       source='canonical-directive-v1:'+json.dumps({**self.evidence, 'method': self.source}, sort_keys=True, separators=(',', ':')))
+        return row
+
+    @classmethod
+    def from_row(cls, row: Dict[str, Any]) -> "Directive":
+        def _split(v: Any) -> List[str]:
+            return [t for t in str(v or "").split(" ") if t]
+        source = row.get('source', 'owner_explicit') or 'owner_explicit'
+        evidence = None
+        if source.startswith('canonical-directive-v1:'):
+            evidence = json.loads(source.removeprefix('canonical-directive-v1:'))
+            source = evidence.get('method', 'owner_explicit')
+        return cls(
+            evidence=evidence,
+            id=row["id"],
+            subject=row["subject"],
+            polarity=Polarity(row["polarity"]),
+            raw_text=row.get("raw_text", "") or "",
+            match_terms=_split(row.get("match_terms")),
+            entity_ids=_split(row.get("entity_ids")),
+            action_kinds=_split(row.get("action_kinds")),
+            source=source,
+            confidence=float(row.get("confidence", 0.9) or 0.9),
+            status=DirectiveStatus(row.get("status", "active")),
+            level=(Level(row["level"]) if row.get("level") else None),
+            created_at=float(row.get("created_at") or time.time()),
+            updated_at=float(row.get("updated_at") or time.time()),
+            expires_at=(float(row["expires_at"]) if row.get("expires_at") not in (None, "") else None),
+        )

apsimo/directives/service.py

@@ -0,0 +1,372 @@
+"""DirectiveManager -- capture, store, revoke, and enforce owner boundaries.
+
+The single entry point the rest of Colony uses: the turn pipeline calls
+``capture_from_message`` on owner messages; the executor / delivery /
+generation chokepoints call ``guard.check(action)``; the context assembler
+calls ``guard.context_brief()``.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import time
+from dataclasses import dataclass, field
+from typing import Any, List, Optional
+
+from apsimo.directives.extractor import extract_directives, is_revocation
+from apsimo.directives.guard import DirectiveGuard, Action, Verdict
+from apsimo.directives.models import (
+    Directive, Level, Polarity, normalize_terms,
+)
+from apsimo.directives.store import DirectiveStore
+
+logger = logging.getLogger(__name__)
+
+# Affirmations that confirm a pending boundary lift. Deliberately short/explicit.
+_AFFIRM = re.compile(
+    r"^\s*(?:yes|yep|yeah|yup|confirm(?:ed)?|do it|go ahead|correct|affirmative|"
+    r"sure|ok(?:ay)?|please do|resume it|lift it)\b", re.IGNORECASE,
+)
+# How long a pending confirmation stays valid (owner must confirm promptly).
+_PENDING_TTL_SECS = 900.0
+
+# Subjects that start with an unresolved anaphor or a dangling conjunction are
+# sentence FRAGMENTS ("that and wipe it from colony", "or manage this job",
+# "attempt them"): the real referent was lost at extraction, so storing them
+# creates boundaries that fuzzy-match everything and nothing the owner meant.
+# Found live 2026-07-05: a store poisoned with these plus test canaries blocked
+# every routine job once the worker governor went live.
+_ANAPHORA_LEAD = re.compile(
+    r"^(?:that|this|it|them|those|these|him|her|or|and|but|so|then|there|"
+    r"y|x)\b", re.IGNORECASE,
+)
+
+
+@dataclass
+class CaptureResult:
+    captured: List[Directive] = field(default_factory=list)
+    revoked: List[Directive] = field(default_factory=list)
+    ack: Optional[str] = None                 # confirmation echo for the owner
+    needs_confirmation: Optional[str] = None  # a lift awaiting explicit confirmation
+
+    def any(self) -> bool:
+        return bool(self.captured or self.revoked or self.ack or self.needs_confirmation)
+
+
+class DirectiveManager:
+    def __init__(self, store: DirectiveStore) -> None:
+        self.store = store
+        self.guard = DirectiveGuard(store)
+        # Pending boundary lift awaiting explicit owner confirmation (1c).
+        self._pending_lift: Optional[dict] = None
+        # One-shot acknowledgment to echo back to the owner (1a).
+        self._last_ack: Optional[str] = None
+        self._ack_ids: List[str] = []
+
+    # -- capture -------------------------------------------------------
+    def capture_from_message(self, message: str, *, source: str = "owner_explicit",
+                             source_id: str = "", contact_id: str = "") -> CaptureResult:
+        """Extract directives from an OWNER message and persist them.
+
+        Asymmetric friction (1c): SETTING a boundary is one-turn easy; LIFTING
+        one is staged as a pending confirmation and only applied when the owner
+        explicitly confirms on a subsequent message. Caller MUST gate to owner.
+        """
+        result = CaptureResult()
+        text = (message or "").strip()
+
+        # 0) Machine-origin text never sets or lifts a boundary: skill/system/
+        # interrupted-turn residue that reaches this path with the owner's
+        # contact id (cron review prompts, tool echoes) must not become
+        # standing directives. (Live incident 2026-07-05: the executor's own
+        # refusal text "Do not attempt them" was re-captured as a boundary.)
+        try:
+            from apsimo.delivery.reachout_policy import is_system_origin
+            if is_system_origin(text):
+                return result
+        except ImportError:
+            pass
+
+        # 1) If a lift is pending, ONLY an explicit affirmation on the immediate
+        #    next message confirms it; anything else clears it (fail-safe: a
+        #    prohibition is never lifted by an attribution error or stray text).
+        if self.store.ledger is not None and not source_id:
+            return result
+        if self._pending_lift is not None and not self._pending_lift_current():
+            self._pending_lift = None
+        if self._pending_lift is not None:
+            expired = time.time() - self._pending_lift["ts"] > _PENDING_TTL_SECS
+            if not expired and _AFFIRM.match(text):
+                if self.store.ledger is not None:
+                    from .evidence import bind
+                    if bind(self.store.ledger, source_id=source_id, contact_id=contact_id,
+                            message=text, clause=text) is None:
+                        return result
+                revoked = self._apply_revocation_ids(self._pending_lift["ids"])
+                subj = self._pending_lift["subject"]
+                self._pending_lift = None
+                result.revoked = revoked
+                result.ack = f"Confirmed. I will resume {subj}."
+                self._last_ack = result.ack
+                self._ack_ids = [d.id for d in revoked]
+                return result
+            # not confirmed -> the boundary stays; drop the pending lift
+            self._pending_lift = None
+
+        found = extract_directives(text, source=source)
+
+        # 2) A revocation stages a pending confirmation (never lifts immediately).
+        revocations = [d for d in found if is_revocation(d)]
+        if revocations:
+            rev = revocations[0]
+            terms = set(rev.match_terms or normalize_terms(rev.subject))
+            matches = [d for d in self.store.active(polarity=Polarity.PROHIBIT)
+                       if set(d.match_terms) & terms]
+            if matches:
+                evidence = None
+                if self.store.ledger is not None:
+                    from .evidence import bind
+                    evidence = bind(self.store.ledger, source_id=source_id, contact_id=contact_id,
+                                    message=text, clause=text)
+                    if evidence is None:
+                        return result
+                self._pending_lift = {
+                    "subject": rev.subject, "ids": [d.id for d in matches],
+                    "ts": time.time(), "evidence": evidence,
+                }
+                subs = "; ".join(d.raw_text or d.subject for d in matches)
+                result.needs_confirmation = (
+                    f"You asked me to resume: {rev.subject}. That lifts a boundary "
+                    f"you set ({subs}). Confirm and I will resume it; otherwise it stays in place."
+                )
+            return result
+
+        # 3) New prohibitions / requirements are stored immediately -- after
+        # the quality gates: fragments are refused and duplicates never pile up.
+        for d in found:
+            if not self._subject_acceptable(d):
+                logger.info("Directive capture skipped: degenerate subject")
+                continue
+            if self._duplicate_active(d):
+                logger.debug("Directive capture skipped: duplicate active rule")
+                continue
+            if source_id:
+                from .evidence import bind
+                d.evidence = bind(self.store.ledger, source_id=source_id, contact_id=contact_id,
+                                  message=text, clause=d.raw_text)
+                if d.evidence is None:
+                    continue
+            self.store.add(d)
+            result.captured.append(d)
+        if result.captured:
+            parts = []
+            for d in result.captured:
+                # The echo STATES the interpretation (tiered semantics) so the
+                # owner can correct it in one turn.
+                from apsimo.directives.models import GLOBAL_PAUSE_TERM
+                if GLOBAL_PAUSE_TERM in (d.match_terms or []):
+                    parts.append(
+                        "GLOBAL PAUSE engaged: I will take no autonomous "
+                        "actions until you tell me to resume (say 'resume "
+                        "autonomy')")
+                elif d.polarity != Polarity.PROHIBIT:
+                    parts.append(f"I will make sure to {d.subject}")
+                elif d.level == Level.OBSERVE:
+                    parts.append(
+                        f"full blackout on {d.subject}: I will not act on it "
+                        "or look at it")
+                else:
+                    parts.append(
+                        f"I will stop acting on {d.subject}. I will still keep "
+                        "awareness of it; say 'don't even look at it' for a "
+                        "full blackout")
+            result.ack = "Noted: " + "; ".join(parts) + "."
+            self._last_ack = result.ack
+            self._ack_ids = [d.id for d in result.captured]
+        return result
+
+    # -- capture quality gates ------------------------------------------
+    _PRONOUNS = frozenset({"it", "that", "this", "them", "those", "these",
+                           "him", "her", "they", "he", "she"})
+
+    def _subject_acceptable(self, d: Directive) -> bool:
+        """A storable subject names something concrete: no unresolved
+        anaphora fragments, and at least one substantive term survives
+        normalization."""
+        subj = (d.subject or "").strip()
+        if not subj:
+            return False
+        if _ANAPHORA_LEAD.match(subj):
+            return False
+        raw_tokens = re.findall(r"[a-z]+", subj.lower())
+        terms = d.match_terms or normalize_terms(subj)
+        substantive = [t for t in terms
+                       if len(t) >= 4 and t not in self._PRONOUNS]
+        if not substantive:
+            return False
+        # A bare pronoun object with a thin subject ("attempt them",
+        # "resend it") is an unresolved reference: the thing the owner meant
+        # never made it into the subject.
+        if any(t in self._PRONOUNS for t in raw_tokens) and len(substantive) < 2:
+            return False
+        return True
+
+    def _duplicate_active(self, d: Directive) -> bool:
+        """An active directive with the same polarity and identical
+        normalized terms already covers this capture."""
+        key = set(d.match_terms or normalize_terms(d.subject))
+        if not key:
+            return False
+        try:
+            for e in self.store.active(polarity=d.polarity):
+                if set(e.match_terms or []) == key:
+                    return True
+        except Exception:
+            pass
+        return False
+
+    def consume_ack(self) -> Optional[str]:
+        """Return and clear the one-shot acknowledgment (echoed once)."""
+        ack, self._last_ack = self._last_ack, None
+        identifiers, self._ack_ids = self._ack_ids, []
+        if any(self.store.get(identifier) is None for identifier in identifiers):
+            return None
+        return ack
+
+    def _pending_lift_current(self) -> bool:
+        pending = self._pending_lift
+        if (pending is None or time.time() - pending["ts"] > _PENDING_TTL_SECS
+                or not any(self.store.get(identifier) for identifier in pending["ids"])):
+            return False
+        if self.store.ledger is not None:
+            from .evidence import _message
+            return bool(pending.get("evidence") and _message(self.store.ledger, pending["evidence"]) is not None)
+        return True
+
+    def pending_confirmation(self) -> Optional[str]:
+        """The current pending boundary-lift prompt, if any (for context echo)."""
+        if self._pending_lift is None:
+            return None
+        if not self._pending_lift_current():
+            self._pending_lift = None
+            return None
+        subj = self._pending_lift["subject"]
+        return f"AWAITING CONFIRMATION: the owner asked to resume {subj}; do not resume until they confirm."
+
+    def _apply_revocation_ids(self, ids: List[str]) -> List[Directive]:
+        revoked = []
+        for did in ids:
+            d = self.store.get(did)
+            if d and self.store.revoke(did):
+                revoked.append(d)
+                logger.info("Directive revoked by owner (confirmed): id=%s", did)
+        return revoked
+
+    def add_explicit(self, subject: str, polarity: str = "prohibit",
+                     raw_text: str = "", source: str = "owner_explicit",
+                     entity_ids: Optional[List[str]] = None) -> Directive:
+        d = Directive(
+            subject=subject, polarity=Polarity(polarity), raw_text=raw_text or subject,
+            source=source, entity_ids=entity_ids or [],
+        )
+        return self.store.add(d)
+
+    # -- boundary-respecting critical flag (high-severity path) ---------
+    def set_delivery_router(self, router: Any) -> None:
+        """Async callable(payload)->bool routing through the guarded reach-out
+        path. Used ONLY for the once-per-boundary critical flag."""
+        self._delivery_router = router
+
+    async def flag_critical(self, subject: str, finding: str,
+                            severity: float = 0.9) -> dict:
+        """Under an ACT boundary, reflection may surface something critical
+        (security vulnerability, data loss, financial risk). Correct behavior:
+        an internal note plus AT MOST ONE flag surfaced to the owner through
+        the guarded reach-out path, clearly marked as boundary-respecting.
+        Never silent action; never silent omission of a critical fact.
+        """
+        import os
+        try:
+            threshold = float(os.environ.get("COLONY_BOUNDARY_FLAG_MIN_SEVERITY", "0.85"))
+        except (TypeError, ValueError):
+            threshold = 0.85
+        logger.info("boundary-concern noted (severity=%.2f): %s -- %s",
+                    severity, subject, finding[:160])
+        if severity < threshold:
+            return {"flagged": False, "reason": "below_threshold",
+                    "noted_internally": True}
+
+        # Which active prohibition covers this subject?
+        terms = set(normalize_terms(subject))
+        match = None
+        for d in self.store.active(polarity=Polarity.PROHIBIT):
+            if set(d.match_terms) & terms:
+                match = d
+                break
+        if match is None:
+            return {"flagged": False, "reason": "no_matching_boundary",
+                    "noted_internally": True}
+        if self.store.has_flag(match.id):
+            return {"flagged": False, "reason": "already_flagged_once",
+                    "noted_internally": True}
+        if not self.store.record_flag(match.id, finding, severity):
+            return {"flagged": False, "reason": "already_flagged_once",
+                    "noted_internally": True}
+
+        delivered = False
+        router = getattr(self, "_delivery_router", None)
+        if router is not None:
+            try:
+                from apsimo.proposals import Proposal, proposal_to_payload
+                prop = Proposal(
+                    title=f"Boundary-respecting flag: {subject[:60]}",
+                    finding=(f"You asked me to leave {match.subject} alone, and I have. "
+                             f"But you should know: {finding}"),
+                    why_it_helps="a critical fact should never be silently omitted",
+                    suggested_action="Tell me whether to keep hands off or investigate.",
+                    source=f"boundary-flag:{match.id}",
+                    initiative_type="proposal",
+                    confidence=min(1.0, max(0.0, severity)),
+                )
+                delivered = bool(await router(proposal_to_payload(prop)))
+            except Exception:
+                logger.debug("boundary flag delivery failed", exc_info=True)
+        logger.warning(
+            "BOUNDARY-RESPECTING CRITICAL FLAG surfaced once for [%s] %r: %s",
+            match.id, match.subject, finding[:200],
+        )
+        return {"flagged": True, "directive_id": match.id, "delivered": delivered}
+
+    # -- entity-scoped matching (2) ------------------------------------
+    def set_entity_index(self, entities: dict) -> None:
+        """Provide {entity_id: [names/aliases]} so boundaries resolve by entity."""
+        self.guard.set_entity_index(entities)
+
+    async def refresh_entity_index(self, world_store: Any, limit: int = 500) -> int:
+        """Load entities + aliases from the world model into the guard index."""
+        if world_store is None:
+            return 0
+        try:
+            ents = await world_store.find_entities(query="", limit=limit)
+        except Exception:
+            return 0
+        mapping = {}
+        for e in ents or []:
+            eid = getattr(e, "id", None) or (e.get("id") if isinstance(e, dict) else None)
+            name = getattr(e, "name", None) or (e.get("name") if isinstance(e, dict) else None)
+            aliases = getattr(e, "aliases", None) or (e.get("aliases") if isinstance(e, dict) else []) or []
+            if eid and name:
+                mapping[eid] = [name] + list(aliases)
+        self.guard.set_entity_index(mapping)
+        return len(mapping)
+
+    # -- enforce -------------------------------------------------------
+    def check(self, action: Action) -> Verdict:
+        return self.guard.check(action)
+
+    def context_brief(self) -> str:
+        return self.guard.context_brief()
+
+    def active(self) -> List[Directive]:
+        return self.store.active()