agentgov-core 0.1.0__py3-none-any.whl

agentgov_core/cedar.py

@@ -0,0 +1,56 @@
+"""cedar-agent client (permitio/cedar-agent HTTP API).
+
+Runs schemaless locally: we load the policy set and evaluate with an inline context
+carrying { employment, classification }. A Cedar *forbid* overrides *permit*, which is
+how the contractor+RESTRICTED denial works.
+"""
+import re
+
+import httpx
+
+from .config import settings
+
+TIMEOUT = 10.0
+
+
+def split_statements(text: str) -> list[str]:
+    """cedar-agent stores ONE Cedar statement per policy entry. Strip // comments and
+    split the policy set on statement terminators (';' only ends statements here)."""
+    no_comments = "\n".join(re.sub(r"//.*$", "", line) for line in text.splitlines())
+    return [s.strip() + ";" for s in no_comments.split(";") if s.strip()]
+
+
+class Cedar:
+    def __init__(self, base_url=None):
+        self.base = (base_url or settings.CEDAR_URL).rstrip("/")
+
+    def load_policies(self, policy_text: str | None = None):
+        """Replace the cedar-agent policy set with services/policy/policies.cedar."""
+        if policy_text is None:
+            with open(settings.CEDAR_POLICIES_PATH) as f:
+                policy_text = f.read()
+        # cedar-agent stores a list of {id, content}, one statement each. PUT replaces the set.
+        body = [{"id": f"agentgov_{i}", "content": s} for i, s in enumerate(split_statements(policy_text))]
+        r = httpx.put(f"{self.base}/v1/policies", json=body, timeout=TIMEOUT)
+        r.raise_for_status()
+        return r.json()
+
+    def is_authorized(self, principal_id: str, action: str, resource_id: str, context: dict,
+                      resource_type: str = "Agent") -> bool:
+        """Return True on Allow. action is 'discover' | 'use'. ``resource_type`` is ``Agent``
+        or (Phase 2) ``McpServer`` — the classification/contractor policies are written
+        resource-agnostic on purpose, so a governed MCP server is judged by exactly the same
+        rules as an agent."""
+        body = {
+            "principal": f'User::"{principal_id}"',
+            "action": f'Action::"{action}"',
+            "resource": f'{resource_type}::"{resource_id}"',
+            "context": context,
+        }
+        r = httpx.post(f"{self.base}/v1/is_authorized", json=body, timeout=TIMEOUT)
+        r.raise_for_status()
+        decision = r.json().get("decision", "Deny")
+        return str(decision).lower() == "allow"
+
+
+cedar = Cedar()

agentgov_core/config.py

@@ -0,0 +1,128 @@
+"""Runtime configuration for registry-api (env-driven; local defaults for docker-compose)."""
+import os
+
+
+class Settings:
+    # Path-prefix awareness (BUILD_PLAN §9). Locally the api answers at /assets/registry/api.
+    ROOT_PATH = os.getenv("ROOT_PATH", "/assets/registry/api")
+
+    # Postgres (spine).
+    DB_URL = os.getenv(
+        "DB_URL", "postgresql://agentgov:dev@localhost:5432/agentgov"
+    )
+
+    # OpenFGA (spine). Store is resolved by name so ids need not be plumbed around.
+    OPENFGA_API_URL = os.getenv("OPENFGA_API_URL", "http://localhost:8080")
+    OPENFGA_STORE_NAME = os.getenv("OPENFGA_STORE_NAME", "agentgov")
+
+    # Cedar (spine).
+    CEDAR_URL = os.getenv("CEDAR_URL", "http://localhost:8180")
+    # Local-dev-only convenience default (Cedar.load_policies() reads this when called with no
+    # explicit policy_text, which is how registry-api's own startup calls it — see main.py).
+    # `services/policy/` is an outer-repo fixture this shared package has no business locating via
+    # __file__ trickery (that broke when this module moved out of services/registry-api/app/ in
+    # Phase 5 §5.8 — __file__ no longer sits inside the repo tree at a fixed depth). Relative-to-cwd
+    # is correct here because run_phase*.sh always launches registry-api's uvicorn process with cwd
+    # = services/registry-api (`cd services/registry-api && ... exec uvicorn ...`), never repo root.
+    # NOT reachable at all inside the deployed Docker image today (services/policy/ isn't copied in)
+    # — pre-existing gap, not introduced or fixed by this change; real deployments would need it
+    # added to the Dockerfile if/when this startup call needs to succeed there too.
+    CEDAR_POLICIES_PATH = os.getenv("CEDAR_POLICIES_PATH", "../policy/policies.cedar")
+
+    # Local mock-Okta JWT verification. In real Okta this is a JWKS URL; locally we verify
+    # against a PEM public key on disk (no network dependency for the demo). Same cwd-relative
+    # reasoning as CEDAR_POLICIES_PATH above — real deployments never hit this path at all, they
+    # set JWT_JWKS_URL instead.
+    JWT_PUBLIC_KEY_PATH = os.getenv("JWT_PUBLIC_KEY_PATH", "../../local/identity/keys/public.pem")
+    JWT_ISSUER = os.getenv("JWT_ISSUER", "https://mock-okta.receptor.local/oauth2")
+    JWT_AUDIENCE = os.getenv("JWT_AUDIENCE", "agent-registry")
+    # Real Okta: set JWT_JWKS_URL to the authz server's JWKS
+    # (https://<domain>/oauth2/<authServerId>/v1/keys) and JWT_ISSUER to its issuer.
+    # When set, tokens are verified against Okta's rotating keys instead of the local PEM;
+    # when empty (default), the local mock PEM path is used. Nothing else changes.
+    JWT_JWKS_URL = os.getenv("JWT_JWKS_URL", "")
+    # Allow disabling signature verification only for offline unit poking; default on.
+    JWT_VERIFY = os.getenv("JWT_VERIFY", "1") == "1"
+
+    # OTel. If no OTLP endpoint is set we still emit spans to stdout (ConsoleSpanExporter)
+    # so the Phase-0 DoD ("discover emits a trace w/ authz span-event") is observable locally.
+    OTLP_ENDPOINT = os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT", "")
+    OTEL_CONSOLE = os.getenv("OTEL_CONSOLE", "1") == "1"
+    SERVICE_NAME = os.getenv("OTEL_SERVICE_NAME", "registry-api")
+    # Phase 3 — the SDK default (60s) makes SigNoz-backed usage assertions slow to observe
+    # locally; the local test harness shortens this the same way it shortens ACCESS_TTL_MINUTES.
+    OTEL_METRIC_EXPORT_INTERVAL_MS = int(os.getenv("OTEL_METRIC_EXPORT_INTERVAL_MS", "60000"))
+
+    # Phase 1 — Temporal (spine).
+    TEMPORAL_ADDRESS = os.getenv("TEMPORAL_ADDRESS", "localhost:7233")
+    TEMPORAL_TASK_QUEUE = os.getenv("TEMPORAL_TASK_QUEUE", "agentgov-access")
+
+    # Phase 1 — ServiceNow. Local dev talks to the mock shim (local/servicenow_mock);
+    # swap SERVICENOW_URL to the real PDI once provisioned, hook contract stays identical.
+    SERVICENOW_URL = os.getenv("SERVICENOW_URL", "http://localhost:8300")
+    # Shared secret authenticating the ServiceNow -> registry-api webhook (dev-only default;
+    # real deployments source this from AWS Secrets Manager per CLAUDE.md).
+    SERVICENOW_WEBHOOK_SECRET = os.getenv("SERVICENOW_WEBHOOK_SECRET", "local-dev-servicenow-secret")
+
+    # Governance policy knobs (BUILD_PLAN Phase 1 DoD: "10-min TTL expiry"). Configurable via
+    # env so the local test harness can shrink them for fast iteration; the demo/prod default
+    # is the real 10-minute TTL. Never accepted as a per-request client override.
+    ACCESS_TTL_MINUTES = float(os.getenv("ACCESS_TTL_MINUTES", "10"))
+    ACCESS_SLA_MINUTES = float(os.getenv("ACCESS_SLA_MINUTES", "60"))
+
+    # ---------------------------------------------------------------- Phase 1 seam: real ServiceNow
+    # Table-API auth for the real PDI (docs/setup/servicenow.md §4/§6). Empty = the local mock,
+    # which needs no auth and returns bare records; set both to switch to the real instance.
+    SERVICENOW_USER = os.getenv("SERVICENOW_USER", "")
+    SERVICENOW_PASSWORD = os.getenv("SERVICENOW_PASSWORD", "")
+
+    # ---------------------------------------------------------------- Phase 2: four hosts
+    # 'mock' points every adapter at local/hosts_mock (same contract, no cloud spend);
+    # 'real' points at the platforms themselves. Only URLs/credentials differ — BUILD_PLAN §Phase 2.
+    HOSTS_MODE = os.getenv("AGENTGOV_HOSTS_MODE", "mock")
+    HOSTS_MOCK_URL = os.getenv("AGENTGOV_HOSTS_MOCK_URL", "http://localhost:8400")
+
+    LITELLM_URL = os.getenv("LITELLM_URL", "")            # real: http://litellm:4000
+    LITELLM_MASTER_KEY = os.getenv("LITELLM_MASTER_KEY", "sk-agentgov-local-master")
+
+    # AgentCore: the GATEWAY's credentials. Never the user's, and never a static key in real mode —
+    # app/hosts/agentcore.py::_gateway_credentials() resolves the ECS task role's temporary STS
+    # credentials from the ambient AWS chain instead (§5.7). These two are MOCK-ONLY fallbacks
+    # (local/hosts_mock doesn't touch real AWS, so fixed demo values are fine there).
+    AGENTCORE_URL = os.getenv("AGENTCORE_URL", "")
+    AGENTCORE_REGION = os.getenv("AGENTCORE_REGION", "us-east-1")
+    AGENTCORE_ACCESS_KEY_ID = os.getenv("AGENTCORE_ACCESS_KEY_ID", "AKIAAGENTGOVDEMO0000")
+    AGENTCORE_SECRET_ACCESS_KEY = os.getenv("AGENTCORE_SECRET_ACCESS_KEY", "agentgov-local-dev-agentcore-secret")
+
+    DATABRICKS_URL = os.getenv("DATABRICKS_URL", "")      # real: https://<workspace>.cloud.databricks.com
+    DATABRICKS_UC_SECURABLE = os.getenv("DATABRICKS_UC_SECURABLE", "iops.manufacturing")
+    # Privileged admin bearer (PAT or OAuth token scoped to SCIM + Unity Catalog + Apps) the
+    # GATEWAY uses for JIT identity: SCIM CREATE USER + UC GRANT/REVOKE. Never a user token.
+    # Empty in mock (the mock host doesn't check it).
+    DATABRICKS_TOKEN = os.getenv("DATABRICKS_TOKEN", "")
+
+    SNOWFLAKE_URL = os.getenv("SNOWFLAKE_URL", "")        # real: https://<account>.snowflakecomputing.com
+    SNOWFLAKE_ROLE_SCOPE = os.getenv("SNOWFLAKE_ROLE_SCOPE", "session:role:GD_CLINICAL_READER")
+    # Privileged key-pair for JIT CREATE USER / GRANT / REVOKE (the gateway's admin identity).
+    # Store the PRIVATE KEY, not a pre-minted JWT — key-pair JWTs expire in <=1h, so the adapter
+    # signs a fresh one per call (app/hosts/snowflake.py::_admin_jwt). Never a user token.
+    # Secret: agentgov/prod/snowflake-admin {account,user,private_key,private_key_passphrase}.
+    SNOWFLAKE_ADMIN_ACCOUNT = os.getenv("SNOWFLAKE_ADMIN_ACCOUNT", "")           # e.g. AULMROR-NLC43968
+    SNOWFLAKE_ADMIN_USER = os.getenv("SNOWFLAKE_ADMIN_USER", "")                # SECURITYADMIN-capable user
+    SNOWFLAKE_ADMIN_ROLE = os.getenv("SNOWFLAKE_ADMIN_ROLE", "SECURITYADMIN")
+    SNOWFLAKE_ADMIN_PRIVATE_KEY = os.getenv("SNOWFLAKE_ADMIN_PRIVATE_KEY", "")   # PKCS8 PEM
+    SNOWFLAKE_ADMIN_PRIVATE_KEY_PASSPHRASE = os.getenv("SNOWFLAKE_ADMIN_PRIVATE_KEY_PASSPHRASE", "")
+
+    # HostDiscoverySync (Temporal Schedule). Shrunk by the local harness so a scheduled sync
+    # is observable during a test run; the demo/prod default is hourly.
+    HOST_SYNC_INTERVAL_MINUTES = float(os.getenv("HOST_SYNC_INTERVAL_MINUTES", "60"))
+    PULL_HOSTS = [h.strip() for h in os.getenv(
+        "AGENTGOV_PULL_HOSTS", "bedrock-agentcore,databricks,snowflake").split(",") if h.strip()]
+
+    # Browser origins allowed to call the API (the local registry-ui page; the deployed UI is
+    # same-origin behind the ALB path prefix, so this stays a dev convenience).
+    CORS_ORIGINS = [o.strip() for o in os.getenv(
+        "CORS_ORIGINS", "http://localhost:8500,http://127.0.0.1:8500").split(",") if o.strip()]
+
+
+settings = Settings()

agentgov_core/db.py

@@ -0,0 +1,491 @@
+"""Thin Postgres access for the registry (psycopg 3)."""
+import os
+import psycopg
+from psycopg.rows import dict_row
+
+from .config import settings
+
+_SCHEMA = os.path.join(os.path.dirname(__file__), "schema.sql")
+
+
+def connect():
+    return psycopg.connect(settings.DB_URL, row_factory=dict_row)
+
+
+def init_schema():
+    with open(_SCHEMA) as f:
+        ddl = f.read()
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(ddl)
+        conn.commit()
+
+
+_AGENT_COLUMNS = (
+    "agent_id", "name", "hosting_mode", "platform", "owning_node", "owner_login",
+    "visibility_scope", "entitlement_scope", "classification", "model", "model_provider",
+    "version", "version_seq", "gxp_relevant", "data_domains", "dependencies", "runtime_auth",
+    "publish_origin", "state", "endpoint", "source_platform", "source_ref", "guardrail_policy",
+    "agent_card", "version_transition_policy",
+)
+_AGENT_DEFAULTS = {"endpoint": None, "source_platform": None, "source_ref": None,
+                   "guardrail_policy": None, "agent_card": "{}",
+                   "version_transition_policy": "carry_forward"}
+
+
+def upsert_agent(a: dict):
+    """Insert/update one agent card. Used by publish, the host-pull normalizer, and the
+    bootstrap seeder. Phase-2 columns default so older callers keep working unchanged."""
+    row = {**_AGENT_DEFAULTS, **a}
+    cols = ", ".join(_AGENT_COLUMNS)
+    vals = ", ".join(f"%({c})s" for c in _AGENT_COLUMNS)
+    updates = ", ".join(f"{c}=EXCLUDED.{c}" for c in _AGENT_COLUMNS if c != "agent_id")
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            f"INSERT INTO agents ({cols}) VALUES ({vals}) "
+            f"ON CONFLICT (agent_id) DO UPDATE SET {updates}, updated_at=now()",
+            row,
+        )
+        conn.commit()
+
+
+def prefilter_agents(user_scopes: list[str]) -> list[dict]:
+    """Candidate *active* agents whose visibility/entitlement scope overlaps the user's scope set.
+    Only 'active' is discoverable — paused/deprecated/quarantine/retired never surface (§2.1)."""
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            """
+            SELECT * FROM agents
+            WHERE state = 'active'
+              AND (visibility_scope && %(s)s OR entitlement_scope && %(s)s)
+            ORDER BY name
+            """,
+            {"s": user_scopes},
+        )
+        return cur.fetchall()
+
+
+def get_agent(agent_id: str) -> dict | None:
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute("SELECT * FROM agents WHERE agent_id = %s", (agent_id,))
+        return cur.fetchone()
+
+
+## ---------------------------------------------------------------- Phase 1: access requests
+
+_ACCESS_REQUEST_DEFAULTS = {"agent_id": None, "resource_type": "agent", "mcp_server_id": None,
+                           "tool_name": None, "renewed_from": None}
+
+
+def create_access_request(row: dict):
+    """`resource_type='agent'` (default) fills `agent_id`; `resource_type='mcp_tool'` (Phase 3
+    tool-granularity JIT) fills `mcp_server_id`/`tool_name` instead and leaves `agent_id` NULL.
+    `renewed_from` (§6.2) links a renewal back to the grant it supersedes."""
+    row = {**_ACCESS_REQUEST_DEFAULTS, **row}
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            """
+            INSERT INTO access_requests
+                (request_id, agent_id, resource_type, mcp_server_id, tool_name, requester_login,
+                 gxp_relevant, renewed_from, state)
+            VALUES
+                (%(request_id)s, %(agent_id)s, %(resource_type)s, %(mcp_server_id)s, %(tool_name)s,
+                 %(requester_login)s, %(gxp_relevant)s, %(renewed_from)s, 'pending')
+            """,
+            row,
+        )
+        conn.commit()
+
+
+def set_access_request_workflow(request_id: str, workflow_id: str, run_id: str):
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            "UPDATE access_requests SET workflow_id=%s, run_id=%s, updated_at=now() WHERE request_id=%s",
+            (workflow_id, run_id, request_id),
+        )
+        conn.commit()
+
+
+def get_access_request(request_id: str) -> dict | None:
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute("SELECT * FROM access_requests WHERE request_id = %s", (request_id,))
+        return cur.fetchone()
+
+
+def update_access_request(request_id: str, **fields):
+    if not fields:
+        return
+    cols = ", ".join(f"{k}=%({k})s" for k in fields)
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            f"UPDATE access_requests SET {cols}, updated_at=now() WHERE request_id=%(request_id)s",
+            {**fields, "request_id": request_id},
+        )
+        conn.commit()
+
+
+def append_audit(request_id: str, event: str, detail: dict | None = None):
+    import json as _json
+
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            "INSERT INTO access_audit (request_id, event, detail) VALUES (%s, %s, %s)",
+            (request_id, event, _json.dumps(detail or {})),
+        )
+        conn.commit()
+
+
+def list_audit(request_id: str) -> list[dict]:
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute("SELECT * FROM access_audit WHERE request_id = %s ORDER BY at", (request_id,))
+        return cur.fetchall()
+
+
+def create_ritm(sys_id: str, request_id: str, ritm_type: str, assignment_group: str | None):
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            """INSERT INTO servicenow_ritms (sys_id, request_id, ritm_type, assignment_group)
+               VALUES (%s, %s, %s, %s) ON CONFLICT (sys_id) DO NOTHING""",
+            (sys_id, request_id, ritm_type, assignment_group),
+        )
+        conn.commit()
+
+
+def set_ritm_state(sys_id: str, state: str):
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute("UPDATE servicenow_ritms SET state=%s WHERE sys_id=%s", (state, sys_id))
+        conn.commit()
+
+
+def list_ritms_for_request(request_id: str) -> list[dict]:
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute("SELECT * FROM servicenow_ritms WHERE request_id = %s", (request_id,))
+        return cur.fetchall()
+
+
+def get_request_id_for_ritm(sys_id: str) -> str | None:
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute("SELECT request_id FROM servicenow_ritms WHERE sys_id = %s", (sys_id,))
+        row = cur.fetchone()
+        return row["request_id"] if row else None
+
+
+def list_pending_ritms() -> list[dict]:
+    """RITMs still 'requested' locally — candidates for the reconciliation poll."""
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute("SELECT * FROM servicenow_ritms WHERE state = 'requested'")
+        return cur.fetchall()
+
+
+## ---------------------------------------------------------------- Phase 2: MCP catalog,
+## host sync runs, publish claims
+
+def set_config(key: str, value):
+    import json as _json
+
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            """INSERT INTO registry_config (key, value) VALUES (%s, %s)
+               ON CONFLICT (key) DO UPDATE SET value=EXCLUDED.value, updated_at=now()""",
+            (key, _json.dumps(value)),
+        )
+        conn.commit()
+
+
+def get_config(key: str, default=None):
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute("SELECT value FROM registry_config WHERE key = %s", (key,))
+        row = cur.fetchone()
+        return row["value"] if row else default
+
+
+def upsert_mcp_server(s: dict):
+    row = {**s, "restricted_tools": list(s.get("tool_personas", {}).keys())}
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            """
+            INSERT INTO mcp_servers (server_id, name, platform, url, classification,
+                data_domains, visibility_scope, entitlement_scope, tools, restricted_tools)
+            VALUES (%(server_id)s, %(name)s, %(platform)s, %(url)s, %(classification)s,
+                %(data_domains)s, %(visibility_scope)s, %(entitlement_scope)s, %(tools)s,
+                %(restricted_tools)s)
+            ON CONFLICT (server_id) DO UPDATE SET
+                name=EXCLUDED.name, platform=EXCLUDED.platform, url=EXCLUDED.url,
+                classification=EXCLUDED.classification, data_domains=EXCLUDED.data_domains,
+                visibility_scope=EXCLUDED.visibility_scope,
+                entitlement_scope=EXCLUDED.entitlement_scope, tools=EXCLUDED.tools,
+                restricted_tools=EXCLUDED.restricted_tools
+            """,
+            row,
+        )
+        conn.commit()
+
+
+def get_mcp_server(server_id: str) -> dict | None:
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute("SELECT * FROM mcp_servers WHERE server_id = %s", (server_id,))
+        return cur.fetchone()
+
+
+def prefilter_mcp_servers(user_scopes: list[str]) -> list[dict]:
+    """Candidate MCP servers whose visibility/entitlement scope overlaps the user's scopes.
+    Same prefilter-then-authorize shape as agents; OpenFGA + Cedar still decide."""
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            """SELECT * FROM mcp_servers
+               WHERE visibility_scope && %(s)s OR entitlement_scope && %(s)s
+               ORDER BY name""",
+            {"s": user_scopes},
+        )
+        return cur.fetchall()
+
+
+def record_sync_run(row: dict):
+    import json as _json
+
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            """INSERT INTO host_sync_runs (run_id, platform, trigger, discovered, quarantined,
+                   unchanged, blocked, detail)
+               VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
+               ON CONFLICT (run_id) DO NOTHING""",
+            (row["run_id"], row["platform"], row["trigger"], row["discovered"],
+             row["quarantined"], row["unchanged"], row["blocked"], _json.dumps(row.get("detail", {}))),
+        )
+        conn.commit()
+
+
+def list_sync_runs(platform: str | None = None, limit: int = 20) -> list[dict]:
+    with connect() as conn, conn.cursor() as cur:
+        if platform:
+            cur.execute("SELECT * FROM host_sync_runs WHERE platform=%s ORDER BY at DESC LIMIT %s",
+                        (platform, limit))
+        else:
+            cur.execute("SELECT * FROM host_sync_runs ORDER BY at DESC LIMIT %s", (limit,))
+        return cur.fetchall()
+
+
+def create_publish_claim(row: dict):
+    import json as _json
+
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            """INSERT INTO publish_claims (claim_id, agent_id, platform, version, version_seq,
+                   gxp_relevant, state, envelope)
+               VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
+               ON CONFLICT (claim_id) DO NOTHING""",
+            (row["claim_id"], row["agent_id"], row["platform"], row["version"], row["version_seq"],
+             row.get("gxp_relevant", False), row.get("state", "pending"),
+             _json.dumps(row.get("envelope", {}))),
+        )
+        conn.commit()
+
+
+def update_publish_claim(claim_id: str, **fields):
+    import json as _json
+
+    if not fields:
+        return
+    if "envelope" in fields and not isinstance(fields["envelope"], str):
+        fields["envelope"] = _json.dumps(fields["envelope"])
+    cols = ", ".join(f"{k}=%({k})s" for k in fields)
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            f"UPDATE publish_claims SET {cols}, updated_at=now() WHERE claim_id=%(claim_id)s",
+            {**fields, "claim_id": claim_id},
+        )
+        conn.commit()
+
+
+def get_publish_claim(claim_id: str) -> dict | None:
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute("SELECT * FROM publish_claims WHERE claim_id = %s", (claim_id,))
+        return cur.fetchone()
+
+
+def get_open_claim_for_agent(agent_id: str) -> dict | None:
+    """The claim still awaiting its owner (or ServiceNow) for this agent, if any."""
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            """SELECT * FROM publish_claims
+               WHERE agent_id=%s AND state IN ('pending','claimed','awaiting_servicenow')
+               ORDER BY version_seq DESC, created_at DESC LIMIT 1""",
+            (agent_id,),
+        )
+        return cur.fetchone()
+
+
+def list_quarantined_agents() -> list[dict]:
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute("SELECT * FROM agents WHERE state='quarantine' ORDER BY name")
+        return cur.fetchall()
+
+
+def create_ritm_correlated(sys_id: str, correlation_id: str, ritm_type: str,
+                           assignment_group: str | None, kind: str = "access"):
+    """Phase-2 RITM insert that records WHICH workflow family the RITM belongs to."""
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            """INSERT INTO servicenow_ritms (sys_id, request_id, ritm_type, assignment_group, correlation_kind)
+               VALUES (%s, %s, %s, %s, %s) ON CONFLICT (sys_id) DO NOTHING""",
+            (sys_id, correlation_id, ritm_type, assignment_group, kind),
+        )
+        conn.commit()
+
+
+def get_ritm_row(sys_id: str) -> dict | None:
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute("SELECT * FROM servicenow_ritms WHERE sys_id = %s", (sys_id,))
+        return cur.fetchone()
+
+
+def set_state(agent_id: str, state: str, watermark_seq: int | None = None):
+    """Transition an agent's lifecycle state; optionally raise the deprecation watermark."""
+    with connect() as conn, conn.cursor() as cur:
+        if watermark_seq is None:
+            cur.execute(
+                "UPDATE agents SET state=%s, updated_at=now() WHERE agent_id=%s",
+                (state, agent_id),
+            )
+        else:
+            cur.execute(
+                """UPDATE agents SET state=%s, updated_at=now(),
+                   deprecated_watermark_seq=GREATEST(COALESCE(deprecated_watermark_seq, 0), %s)
+                   WHERE agent_id=%s""",
+                (state, watermark_seq, agent_id),
+            )
+        conn.commit()
+
+
+def schedule_sunset(agent_id: str, sunset_at, reason: str = ""):
+    """§6.4: state -> `sunsetting` (deprecated-but-still-serving, §2.1's one new state) +
+    record when/why. Deliberately does NOT touch `deprecated_watermark_seq` — that's raised
+    only when `SunsetVersion` actually fires, matching how the existing watermark semantics
+    ("blocks resurrection of a deprecated version") were never meant to apply to a version
+    that's still actively serving during its grace window."""
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            "UPDATE agents SET state='sunsetting', sunset_at=%s, sunset_reason=%s, updated_at=now() WHERE agent_id=%s",
+            (sunset_at, reason, agent_id),
+        )
+        conn.commit()
+
+
+def clear_sunset(agent_id: str, to_state: str = "active"):
+    """Cancel a scheduled sunset (back to `active`) or clear the columns once `SunsetVersion`
+    has finished (the caller then sets the real `deprecated` state separately via `set_state`)."""
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            "UPDATE agents SET state=%s, sunset_at=NULL, sunset_reason=NULL, updated_at=now() WHERE agent_id=%s",
+            (to_state, agent_id),
+        )
+        conn.commit()
+
+
+def set_owner(agent_id: str, new_owner_login: str):
+    """§6.2 owner handoff — the Postgres side; the caller must ALSO delete the old owner's
+    OpenFGA tuple and write the new one (agent_tuples() only ever adds, never removes a stale
+    owner — see app/main.py's transfer_owner endpoint)."""
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            "UPDATE agents SET owner_login=%s, updated_at=now() WHERE agent_id=%s",
+            (new_owner_login, agent_id),
+        )
+        conn.commit()
+
+
+## ---------------------------------------------------------------- Phase 6 §6.1: insights
+
+def list_agents_all() -> list[dict]:
+    """Every agent regardless of lifecycle state — unlike `prefilter_agents`, insights isn't a
+    discovery surface: an owner/steward/admin can ask about a paused or deprecated agent's
+    historical usage too."""
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute("SELECT * FROM agents ORDER BY name")
+        return cur.fetchall()
+
+
+def list_agents_by_platform(platform: str) -> list[dict]:
+    """§6.3 host management — `platform` is the same literal string on every agent card
+    (`agents.platform`) and every `registry_config['hosts']` key, so this is a plain equality
+    filter, not a fuzzy host-lookup."""
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute("SELECT * FROM agents WHERE platform = %s ORDER BY name", (platform,))
+        return cur.fetchall()
+
+
+def list_access_requests(state: str | None = None, agent_id: str | None = None,
+                         requester_login: str | None = None) -> list[dict]:
+    """Backing query for 'current pending requests' / 'active approvals who<->agent<->expiry'
+    (§6.1), and 'my grants' / leaver-cascade lookups (§6.2, `requester_login` added there —
+    §6.1 only ever queried by agent_id)."""
+    clauses, params = ["resource_type = 'agent'"], {}
+    if state:
+        clauses.append("state = %(state)s")
+        params["state"] = state
+    if agent_id:
+        clauses.append("agent_id = %(agent_id)s")
+        params["agent_id"] = agent_id
+    if requester_login:
+        clauses.append("requester_login = %(requester_login)s")
+        params["requester_login"] = requester_login
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            f"SELECT * FROM access_requests WHERE {' AND '.join(clauses)} ORDER BY created_at DESC",
+            params,
+        )
+        return cur.fetchall()
+
+
+def upsert_usage_daily(agent_id: str, day, requests: int, in_tokens: int, out_tokens: int):
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            """
+            INSERT INTO usage_daily (agent_id, day, requests, in_tokens, out_tokens, computed_at)
+            VALUES (%(agent_id)s, %(day)s, %(requests)s, %(in_tokens)s, %(out_tokens)s, now())
+            ON CONFLICT (agent_id, day) DO UPDATE SET
+                requests=EXCLUDED.requests, in_tokens=EXCLUDED.in_tokens, out_tokens=EXCLUDED.out_tokens,
+                computed_at=now()
+            """,
+            {"agent_id": agent_id, "day": day, "requests": requests, "in_tokens": in_tokens,
+             "out_tokens": out_tokens},
+        )
+        conn.commit()
+
+
+def list_usage_daily(agent_id: str | None = None, since_day=None) -> list[dict]:
+    clauses, params = ["1=1"], {}
+    if agent_id:
+        clauses.append("agent_id = %(agent_id)s")
+        params["agent_id"] = agent_id
+    if since_day:
+        clauses.append("day >= %(since_day)s")
+        params["since_day"] = since_day
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            f"SELECT * FROM usage_daily WHERE {' AND '.join(clauses)} ORDER BY day DESC",
+            params,
+        )
+        return cur.fetchall()
+
+
+## ---------------------------------------------------------------- Phase 6 §6.3: host management
+
+def record_host_admin_action(platform: str, action: str, actor: str, reason: str = "", detail: dict | None = None):
+    import json as _json
+
+    with connect() as conn, conn.cursor() as cur:
+        cur.execute(
+            "INSERT INTO host_admin_actions (platform, action, actor, reason, detail) VALUES (%s, %s, %s, %s, %s)",
+            (platform, action, actor, reason, _json.dumps(detail or {})),
+        )
+        conn.commit()
+
+
+def list_host_admin_actions(platform: str | None = None, limit: int = 20) -> list[dict]:
+    with connect() as conn, conn.cursor() as cur:
+        if platform:
+            cur.execute("SELECT * FROM host_admin_actions WHERE platform=%s ORDER BY at DESC LIMIT %s",
+                        (platform, limit))
+        else:
+            cur.execute("SELECT * FROM host_admin_actions ORDER BY at DESC LIMIT %s", (limit,))
+        return cur.fetchall()