create-egregore 0.20.2 → 0.21.0-runtime-mvp.2

package/runtime/pi/egregore_runtime/lifecycle_cli.py

@@ -0,0 +1,269 @@
+"""Thin shell compatibility adapter for canonical Runtime lifecycle operations."""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import replace
+import json
+import os
+from pathlib import Path
+import sys
+
+from .lifecycle import (
+    AttentionState,
+    LifecycleAction,
+    LifecycleError,
+    LifecyclePlan,
+    LifecyclePolicy,
+    LifecycleRecord,
+    ObligationState,
+)
+from .identity import actor_presentation_name
+from .runtime import local_runtime
+
+
+def _root() -> Path:
+    return Path(os.environ.get("EGREGORE_ROOT") or Path.cwd()).resolve()
+
+
+def _session_id(root: Path) -> str:
+    configured = os.environ.get("EGREGORE_SESSION_ID", "").strip()
+    if configured:
+        return configured
+    try:
+        return (root / ".egregore-session-id").read_text(encoding="utf-8").strip() or "lifecycle-shell"
+    except OSError:
+        return "lifecycle-shell"
+
+
+def _runtime(args: argparse.Namespace):
+    root = _root()
+    runtime = local_runtime(
+        root,
+        push_remote=os.environ.get("EGREGORE_LIFECYCLE_PUSH", "1") != "0",
+    )
+    if args.days is not None and runtime.lifecycle is not None:
+        runtime.lifecycle.policy = replace(
+            runtime.lifecycle.policy,
+            handoff_ttl_days=args.days,
+            fyi_expiry_days=args.days,
+        )
+    actor = runtime.resolve_actor(session_id=_session_id(root), harness="lifecycle-shell")
+    return runtime, actor
+
+
+def _activity_status(record: LifecycleRecord) -> str:
+    if record.obligation_state is ObligationState.COMPLETED:
+        return "done"
+    if record.obligation_state is ObligationState.CLAIMED:
+        return "claimed"
+    if record.obligation_state is ObligationState.READ:
+        return "read"
+    if record.obligation_state is ObligationState.REVIEW_REQUIRED:
+        return "review_due"
+    if record.attention_state is AttentionState.EXPIRED and record.intent == "fyi":
+        return "expired"
+    return "pending"
+
+
+def _item(actor, record: LifecycleRecord) -> dict[str, object]:
+    recipient = record.recipients[0] if len(record.recipients) == 1 else None
+    author = actor_presentation_name(actor, record.created_by, record.created_by_alias)
+    return {
+        "id": record.artifact_id,
+        "sessionId": record.artifact_id,
+        "topic": record.title,
+        "author": author,
+        "from": author,
+        "authorActorId": record.created_by,
+        "recipient": actor_presentation_name(actor, recipient) if recipient else None,
+        "to": actor_presentation_name(actor, recipient) if recipient else None,
+        "date": record.created_at.date().isoformat(),
+        "filePath": record.canonical_path.removeprefix("memory/"),
+        "status": _activity_status(record),
+        "intent": record.intent or "unclassified",
+        "ageDays": record.age_days,
+        "authority": record.authority_state.value,
+        "attention": record.attention_state.value,
+        "obligation": record.obligation_state.value,
+        "lifecycleRevision": record.lifecycle_revision,
+        "lifecycleReason": record.terminal_reason,
+        "recommendation": record.recommendation,
+        "automaticTransitionSafe": record.automatic_transition_safe,
+        "supersededBy": list(record.superseded_by),
+    }
+
+
+def _plan_json(actor, plan: LifecyclePlan, *, managed_only: bool = False) -> dict[str, object]:
+    records = [record for record in plan.records if record.artifact_type == "handoff"]
+    if managed_only:
+        records = [record for record in records if record.intent in {"action", "feedback", "fyi"}]
+    items = [_item(actor, record) for record in records]
+    safe = [item for item in items if item["automaticTransitionSafe"]]
+    review = [item for item in items if item["recommendation"] == "review"]
+    return {
+        "schema": plan.schema_version,
+        "index_spec_version": plan.index_spec_version,
+        "snapshot_id": plan.snapshot_id,
+        "source_revision": plan.source_revision,
+        "generated_at": plan.generated_at.isoformat(),
+        "authority": "canonical_markdown",
+        "graph_dependency": False,
+        "managed_only": managed_only,
+        "counts": {
+            "handoffs": len(items),
+            "safe_candidates": len(safe),
+            "review_candidates": len(review),
+        },
+        "safe_candidates": safe,
+        "review_candidates": review,
+        "handoffs_to_me": items,
+        "items": items,
+        "warnings": list(plan.warnings),
+        "apply_contract": {
+            "requires_snapshot": True,
+            "confirmation": "APPLY_SAFE_HANDOFF_LIFECYCLE",
+            "age_alone_never_marks_done": True,
+            "attention_expiry_never_completes_obligation": True,
+        },
+    }
+
+
+def _scan(args: argparse.Namespace) -> int:
+    runtime, actor = _runtime(args)
+    plan = runtime.lifecycle_plan(actor, artifact_types=("handoff",), user=args.user)
+    print(json.dumps(_plan_json(actor, plan, managed_only=args.managed_only), separators=(",", ":")))
+    return 0
+
+
+def _action(args: argparse.Namespace) -> int:
+    runtime, actor = _runtime(args)
+    action = {
+        "read": LifecycleAction.ACKNOWLEDGE,
+        "acknowledge": LifecycleAction.ACKNOWLEDGE,
+        "claim": LifecycleAction.CLAIM,
+        "done": LifecycleAction.COMPLETE,
+        "complete": LifecycleAction.COMPLETE,
+        "expire": LifecycleAction.EXPIRE_ATTENTION,
+        "expire_attention": LifecycleAction.EXPIRE_ATTENTION,
+        "reopen": LifecycleAction.REOPEN,
+        "review": LifecycleAction.REQUEST_REVIEW,
+        "request_review": LifecycleAction.REQUEST_REVIEW,
+    }[args.action]
+    receipt = runtime.transition_lifecycle(
+        actor,
+        target_artifact_id=args.target,
+        action=action,
+        reason=args.reason,
+        evidence_ids=tuple(args.evidence),
+        automatic=args.automatic,
+        expected_lifecycle_revision=args.expected_revision,
+        user=args.user,
+    )
+    resulting_status = {
+        LifecycleAction.ACKNOWLEDGE: "read",
+        LifecycleAction.CLAIM: "claimed",
+        LifecycleAction.COMPLETE: "done",
+        LifecycleAction.EXPIRE_ATTENTION: "expired",
+        LifecycleAction.REOPEN: "pending",
+        LifecycleAction.REQUEST_REVIEW: "review_due",
+    }[action]
+    print(
+        json.dumps(
+            {
+                "applied": receipt.status.value != "rejected",
+                "action": action.value,
+                "id": args.target,
+                "event_id": receipt.artifact.artifact_id,
+                "status": resulting_status,
+                "writeback_status": receipt.status.value,
+                "git_revision": receipt.git_revision,
+                "warnings": list(receipt.warnings),
+            },
+            separators=(",", ":"),
+        )
+    )
+    return 0 if receipt.status.value != "rejected" else 3
+
+
+def _apply(args: argparse.Namespace) -> int:
+    runtime, actor = _runtime(args)
+    plan = runtime.lifecycle_plan(actor, artifact_types=("handoff",), user=args.user)
+    if args.snapshot != plan.snapshot_id:
+        raise LifecycleError("snapshot changed; scan again before applying")
+    if args.confirm != "APPLY_SAFE_HANDOFF_LIFECYCLE":
+        raise LifecycleError("explicit lifecycle confirmation is required")
+    receipts = []
+    for record in plan.records:
+        if not record.automatic_transition_safe:
+            continue
+        receipt = runtime.transition_lifecycle(
+            actor,
+            target_artifact_id=record.artifact_id,
+            action=LifecycleAction.EXPIRE_ATTENTION,
+            reason="typed_attention_ttl_elapsed",
+            automatic=True,
+            expected_lifecycle_revision=record.lifecycle_revision,
+            user=args.user,
+        )
+        receipts.append(receipt)
+    print(
+        json.dumps(
+            {
+                **_plan_json(actor, plan, managed_only=args.managed_only),
+                "applied": True,
+                "transitions": {
+                    "attention_expired": len(receipts),
+                    "completed": 0,
+                },
+            },
+            separators=(",", ":"),
+        )
+    )
+    return 0
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="egregore-lifecycle")
+    commands = parser.add_subparsers(dest="command", required=True)
+    for name in ("scan", "apply"):
+        command = commands.add_parser(name)
+        command.add_argument("--days", type=int)
+        command.add_argument("--user")
+        command.add_argument("--managed-only", action="store_true")
+        if name == "apply":
+            command.add_argument("--snapshot", required=True)
+            command.add_argument("--confirm", required=True)
+        command.set_defaults(handler=_scan if name == "scan" else _apply)
+    action = commands.add_parser("action")
+    action.add_argument(
+        "action",
+        choices=(
+            "read", "acknowledge", "claim", "done", "complete", "expire",
+            "expire_attention", "reopen", "review", "request_review",
+        ),
+    )
+    action.add_argument("target")
+    action.add_argument("--reason", default="explicit_user_action")
+    action.add_argument("--evidence", action="append", default=[])
+    action.add_argument("--automatic", action="store_true")
+    action.add_argument("--expected-revision")
+    action.add_argument("--user")
+    action.add_argument("--days", type=int)
+    action.set_defaults(handler=_action)
+    return parser
+
+
+def main() -> int:
+    args = _parser().parse_args()
+    if args.days is not None and not 1 <= args.days <= 365:
+        raise LifecycleError("days must be between 1 and 365")
+    return args.handler(args)
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except (LifecycleError, RuntimeError, ValueError) as exc:
+        print(f"egregore lifecycle: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc

package/runtime/pi/egregore_runtime/notification_cli.py

@@ -0,0 +1,125 @@
+"""Runtime-neutral command adapter for notification consent and delivery."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import sys
+from uuid import uuid4
+
+from .adapters.notification import ShellNotificationTransport
+from .errors import AuthorizationDenied
+from .notifications import NotificationError, NotificationService
+from .runtime import local_runtime
+
+
+def _root() -> Path:
+    return Path(os.environ.get("EGREGORE_ROOT") or Path.cwd()).resolve()
+
+
+def _context():
+    root = _root()
+    runtime = local_runtime(root, push_remote=False)
+    session_path = root / ".egregore-session-id"
+    session_id = os.environ.get("EGREGORE_SESSION_ID")
+    if not session_id and session_path.is_file():
+        session_id = session_path.read_text(encoding="utf-8").splitlines()[0].strip()
+    actor = runtime.resolve_actor(
+        session_id=session_id or f"session_{uuid4().hex}",
+        harness=os.environ.get("EGREGORE_RUNTIME", "shell"),
+    )
+    service = NotificationService(
+        runtime,
+        ShellNotificationTransport(root),
+        root / ".egregore" / "runtime" / "notifications",
+    )
+    return actor, service
+
+
+def _plan(args: argparse.Namespace) -> int:
+    actor, service = _context()
+    message = Path(args.message_file).read_text(encoding="utf-8")
+    result = service.plan(
+        actor,
+        kind=args.kind,
+        recipient=args.recipient,
+        message=message,
+    )
+    print(json.dumps(result, ensure_ascii=False))
+    return 0
+
+
+def _status(args: argparse.Namespace) -> int:
+    del args
+    actor, service = _context()
+    print(json.dumps(service.status(actor), ensure_ascii=False))
+    return 0
+
+
+def _approve(args: argparse.Namespace) -> int:
+    actor, service = _context()
+    result = service.approve(
+        actor,
+        plan_id=args.plan_id,
+        digest=args.digest,
+        confirmation=args.confirmation,
+    )
+    print(json.dumps(result, ensure_ascii=False))
+    return 0
+
+
+def _dispatch(args: argparse.Namespace) -> int:
+    actor, service = _context()
+    result = service.dispatch(
+        actor,
+        plan_id=args.plan_id,
+        approval_token=args.approval_token,
+    )
+    print(json.dumps(result, ensure_ascii=False))
+    return 0
+
+
+def _cancel(args: argparse.Namespace) -> int:
+    actor, service = _context()
+    print(json.dumps(service.cancel(actor, plan_id=args.plan_id), ensure_ascii=False))
+    return 0
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="egregore-notification")
+    commands = parser.add_subparsers(dest="command", required=True)
+    status = commands.add_parser("status")
+    status.set_defaults(handler=_status)
+    plan = commands.add_parser("plan")
+    plan.add_argument("--kind", choices=("group", "send"), required=True)
+    plan.add_argument("--recipient")
+    plan.add_argument("--message-file", required=True)
+    plan.set_defaults(handler=_plan)
+    approve = commands.add_parser("approve")
+    approve.add_argument("plan_id")
+    approve.add_argument("digest")
+    approve.add_argument("confirmation")
+    approve.set_defaults(handler=_approve)
+    dispatch = commands.add_parser("dispatch")
+    dispatch.add_argument("plan_id")
+    dispatch.add_argument("approval_token")
+    dispatch.set_defaults(handler=_dispatch)
+    cancel = commands.add_parser("cancel")
+    cancel.add_argument("plan_id")
+    cancel.set_defaults(handler=_cancel)
+    return parser
+
+
+def main() -> int:
+    args = _parser().parse_args()
+    return args.handler(args)
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except (AuthorizationDenied, NotificationError, OSError, ValueError) as exc:
+        print(f"notification: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc

package/runtime/pi/egregore_runtime/notifications.py

@@ -0,0 +1,230 @@
+"""Actor-bound notification planning and exact-consent dispatch."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+import json
+import os
+from pathlib import Path
+from typing import Callable, Mapping, Protocol
+from uuid import uuid4
+
+from .contracts import ActorContext, Permission, TelemetryEvent
+from .errors import AuthorizationDenied
+from .runtime import EgregoreRuntime
+from .telemetry import TELEMETRY_SCHEMA_VERSION
+
+
+EXACT_NOTIFICATION_CONFIRMATION = "APPROVE_EXACT_NOTIFICATION"
+NOTIFICATION_BINDING_SCHEMA = "egregore-notification-binding/v1"
+
+
+class NotificationError(RuntimeError):
+    """A notification plan or dispatch failed closed."""
+
+
+class NotificationTransport(Protocol):
+    def status(self) -> Mapping[str, object]: ...
+
+    def plan(self, *, kind: str, recipient: str | None, message: str) -> Mapping[str, object]: ...
+
+    def approve(self, *, plan_id: str, digest: str, confirmation: str) -> Mapping[str, object]: ...
+
+    def dispatch(self, *, plan_id: str, approval_token: str) -> Mapping[str, object]: ...
+
+    def cancel(self, *, plan_id: str) -> Mapping[str, object]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class NotificationBinding:
+    plan_id: str
+    digest: str
+    org_id: str
+    actor_id: str
+    session_id: str
+    kind: str
+    recipient: str | None
+
+
+class NotificationService:
+    """Authorize and bind one immutable notification plan to one actor session."""
+
+    def __init__(
+        self,
+        runtime: EgregoreRuntime,
+        transport: NotificationTransport,
+        state_root: Path,
+        *,
+        clock: Callable[[], datetime] | None = None,
+    ) -> None:
+        self.runtime = runtime
+        self.transport = transport
+        self.state_root = state_root.resolve()
+        self.clock = clock or (lambda: datetime.now(UTC))
+
+    def _authorize(
+        self,
+        actor: ActorContext,
+        permission: Permission,
+        resource: str,
+    ) -> None:
+        decision = self.runtime.authorize(actor, permission, (resource,))
+        if not decision.allowed:
+            raise AuthorizationDenied(
+                "; ".join(decision.reasons) or f"notification {permission.value} denied"
+            )
+
+    def status(self, actor: ActorContext) -> Mapping[str, object]:
+        """Return sanitized transport readiness through the Runtime boundary."""
+
+        self._authorize(actor, Permission.READ, "notification:configuration")
+        receipt = self.transport.status()
+        return {
+            "status": str(receipt.get("status") or "unknown"),
+            "configured": bool(receipt.get("configured", False)),
+            "channels": tuple(str(value) for value in receipt.get("channels", ()) if value),
+        }
+
+    def _binding_path(self, plan_id: str) -> Path:
+        if not plan_id or any(character not in "0123456789abcdef" for character in plan_id):
+            raise NotificationError("notification plan id is invalid")
+        return self.state_root / f"{plan_id}.json"
+
+    def _write_binding(self, actor: ActorContext, plan: Mapping[str, object], *, kind: str, recipient: str | None) -> None:
+        plan_id = str(plan.get("plan_id") or "")
+        digest = str(plan.get("digest") or "")
+        if plan.get("status") != "approval_required" or not plan_id or not digest:
+            raise NotificationError("notification transport returned an invalid plan")
+        self.state_root.mkdir(parents=True, exist_ok=True)
+        os.chmod(self.state_root, 0o700)
+        target = self._binding_path(plan_id)
+        temporary = target.with_name(f".{target.name}.tmp")
+        payload = {
+            "schema_version": NOTIFICATION_BINDING_SCHEMA,
+            "plan_id": plan_id,
+            "digest": digest,
+            "org_id": actor.profile.org_id,
+            "actor_id": actor.actor.actor_id,
+            "session_id": actor.session_id,
+            "kind": kind,
+            "recipient": recipient,
+            "created_at": self.clock().astimezone(UTC).isoformat(),
+        }
+        temporary.write_text(json.dumps(payload, sort_keys=True) + "\n", encoding="utf-8")
+        os.chmod(temporary, 0o600)
+        temporary.replace(target)
+
+    def _binding(self, actor: ActorContext, *, plan_id: str, digest: str | None = None) -> NotificationBinding:
+        path = self._binding_path(plan_id)
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            raise NotificationError("notification plan binding is unavailable") from exc
+        if payload.get("schema_version") != NOTIFICATION_BINDING_SCHEMA:
+            raise NotificationError("notification plan binding is invalid")
+        if (
+            payload.get("org_id") != actor.profile.org_id
+            or payload.get("actor_id") != actor.actor.actor_id
+            or payload.get("session_id") != actor.session_id
+        ):
+            raise AuthorizationDenied("notification plan belongs to another actor session")
+        if digest is not None and payload.get("digest") != digest:
+            raise NotificationError("notification plan digest changed; prepare it again")
+        return NotificationBinding(
+            plan_id=plan_id,
+            digest=str(payload["digest"]),
+            org_id=str(payload["org_id"]),
+            actor_id=str(payload["actor_id"]),
+            session_id=str(payload["session_id"]),
+            kind=str(payload["kind"]),
+            recipient=str(payload["recipient"]) if payload.get("recipient") else None,
+        )
+
+    def plan(
+        self,
+        actor: ActorContext,
+        *,
+        kind: str,
+        message: str,
+        recipient: str | None = None,
+    ) -> Mapping[str, object]:
+        clean_kind = kind.strip().casefold()
+        if clean_kind not in {"group", "send"}:
+            raise NotificationError("notification kind must be group or send")
+        clean_message = message.strip()
+        if not clean_message:
+            raise NotificationError("notification message is required")
+        clean_recipient = recipient.strip() if recipient and recipient.strip() else None
+        if clean_kind == "send" and clean_recipient is None:
+            raise NotificationError("direct notification recipient is required")
+        resource = f"notification:{clean_kind}:{clean_recipient or 'organization'}"
+        self._authorize(actor, Permission.SHARE, resource)
+        plan = self.transport.plan(
+            kind=clean_kind,
+            recipient=clean_recipient,
+            message=clean_message,
+        )
+        self._write_binding(actor, plan, kind=clean_kind, recipient=clean_recipient)
+        return plan
+
+    def approve(
+        self,
+        actor: ActorContext,
+        *,
+        plan_id: str,
+        digest: str,
+        confirmation: str,
+    ) -> Mapping[str, object]:
+        if confirmation != EXACT_NOTIFICATION_CONFIRMATION:
+            raise NotificationError("exact notification confirmation is required")
+        binding = self._binding(actor, plan_id=plan_id, digest=digest)
+        resource = f"notification:{binding.kind}:{binding.recipient or 'organization'}"
+        self._authorize(actor, Permission.SHARE, resource)
+        approval = self.transport.approve(
+            plan_id=plan_id,
+            digest=digest,
+            confirmation=confirmation,
+        )
+        if approval.get("status") != "approved" or not approval.get("approval_token"):
+            raise NotificationError("notification transport did not approve the exact plan")
+        return approval
+
+    def dispatch(
+        self,
+        actor: ActorContext,
+        *,
+        plan_id: str,
+        approval_token: str,
+    ) -> Mapping[str, object]:
+        binding = self._binding(actor, plan_id=plan_id)
+        resource = f"notification:{binding.kind}:{binding.recipient or 'organization'}"
+        self._authorize(actor, Permission.SHARE, resource)
+        self._authorize(actor, Permission.EXECUTE, resource)
+        receipt = self.transport.dispatch(plan_id=plan_id, approval_token=approval_token)
+        if receipt.get("status") not in {"sent", "delivered", "partial"}:
+            raise NotificationError("notification dispatch did not return a delivery receipt")
+        self._binding_path(plan_id).unlink(missing_ok=True)
+        try:
+            self.runtime.telemetry.emit(
+                TelemetryEvent(
+                    schema_version=TELEMETRY_SCHEMA_VERSION,
+                    event_id=f"evt_{uuid4().hex}",
+                    event_type="notification.dispatched",
+                    occurred_at=self.clock().astimezone(UTC),
+                    org_id=actor.profile.org_id,
+                    actor_id=actor.actor.actor_id,
+                    session_id=actor.session_id,
+                    org_revision=actor.profile.revision,
+                    metrics={"success": True, "action": binding.kind},
+                )
+            )
+        except Exception:
+            pass
+        return receipt
+
+    def cancel(self, actor: ActorContext, *, plan_id: str) -> Mapping[str, object]:
+        self._binding(actor, plan_id=plan_id)
+        receipt = self.transport.cancel(plan_id=plan_id)
+        self._binding_path(plan_id).unlink(missing_ok=True)
+        return receipt