hermes-agent/tests/wisdom/test_client.py

import json
import base64
import hashlib
from uuid import uuid4

import pytest

from hermes_wisdom.client import (
    Draft,
    WisdomClient,
    WisdomError,
    WisdomNotFound,
    WisdomValidationError,
)
from hermes_wisdom.package import verify_content_files
from hermes_wisdom.delivery import DeliveryReceipt
from hermes_wisdom.client_delivery import receipt_projection


def _draft(**overrides):
    value = {
        "id": "d1",
        "orgId": "o1",
        "ownerUserId": "u1",
        "slug": "my-skill",
        "draftCommit": "sha256:" + "a" * 64,
        "contentHash": "sha256:" + "b" * 64,
        "authorDescription": "Does a task.",
        "authorDescriptionHash": "sha256:" + "c" * 64,
        "state": "ready",
        "packageManifestHash": "sha256:" + "d" * 64,
        "packageManifestSchemaVersion": 1,
        "systemSpec": None,
        "scan": None,
        "scanVerdict": "pass",
        "explanation": None,
        "updatedAt": "now",
    }
    value.update(overrides)
    return value


def test_changes_requested_requires_complete_moderator_metadata():
    with pytest.raises(ValueError, match="moderator return metadata"):
        Draft.model_validate(_draft(state="changes_requested"))
    returned = Draft.model_validate(
        _draft(
            state="changes_requested",
            moderationNote="Remove the hostname.",
            moderationDeciderUserId="moderator-1",
            moderationDecidedAt="2026-08-25T00:00:00Z",
        )
    )
    assert returned.moderationNote == "Remove the hostname."


class Response:
    def __init__(self, status: int, body):
        self.status_code = status
        self._body = body
        self.content = json.dumps(body).encode() if body is not None else b""

    def json(self):
        return self._body

    def raise_for_status(self):
        if self.status_code < 200 or self.status_code >= 300:
            raise RuntimeError(f"HTTP {self.status_code}")


class Session:
    def __init__(self, response):
        self.response = response
        self.calls = []

    def request(self, method, url, **kwargs):
        self.calls.append((method, url, kwargs))
        return self.response

    def get(self, url, **kwargs):
        self.calls.append(("GET", url, kwargs))
        return self.response


def client(response):
    value = WisdomClient.__new__(WisdomClient)
    value.base = "https://gateway.example"
    value.timeout = 7
    value.session = Session(response)
    return value


def delivery_client(**overrides):
    body = {
        "org_id": "o1", "recipient_user_id": "u1", "event_id": "event-1",
        "request_id": str(uuid4()), "reference": {"kind": "candidate", "key": "sha256:" + "a" * 64},
        "state": "claimed", "lease_until": "2026-09-07T12:02:00.000Z", "reason": None,
        **overrides,
    }
    c = client(Response(200, body))
    c.identity = {"owner": "u1", "claims": {"org_id": "o1"}}
    return c, body


def test_delivery_claim_is_minimal_and_does_not_upload_private_metadata():
    c, body = delivery_client()
    result = c.claim_notification_delivery(body["request_id"], body["reference"])
    assert result.state == "claimed"
    assert c.session.calls[0][2]["json"] == {"request_id": body["request_id"], "reference": body["reference"]}
    for reference in [
        {**body["reference"], "skill_name": "private-name"},
        {"kind": "candidate", "key": "private-name"},
        {"kind": "skill", "skill_id": "shared", "version": True, "event_type": "teammate_published"},
        {"kind": "skill", "skill_id": "shared", "version": 0, "event_type": "teammate_published"},
    ]:
        with pytest.raises(WisdomValidationError):
            c.claim_notification_delivery(body["request_id"], reference)
    assert len(c.session.calls) == 1


def operation_client():
    report = {"request_id": str(uuid4()), "operation_key": "sha256:" + "a" * 64,
        "operation": "install", "state": "completed"}
    body = {"org_id": "o1", "recipient_user_id": "u1", "event_id": "e1", "outcome": report,
        "attestation": "client_reported", "duplicate": False}
    c = client(Response(200, body))
    c.identity = {"owner": "u1", "claims": {"org_id": "o1"}}
    return c, body, report


def test_operation_outcome_sends_only_typed_metadata_and_replays_same_identity():
    c, body, report = operation_client()
    result = c.report_operation_outcome("e1", report)
    assert result.attestation == "client_reported"
    assert c.session.calls[0][2]["json"] == report
    assert c.session.calls[0][1].endswith("/agent-led/deliveries/e1/outcomes")
    c.session.response = Response(200, {**body, "duplicate": True})
    assert c.report_operation_outcome("e1", report).duplicate is True
    assert c.session.calls[1][2]["json"] == report


@pytest.mark.parametrize("patch", [
    {"state": "queued"}, {"operation": "share"}, {"state": "verified"},
    {"operation_key": "local-consent-secret"}, {"description": "private-skill-description"},
    {"receipt": "local-consent-token"}, {"user_id": "override"}, {"request_id": "bad"},
])
def test_operation_outcome_refuses_invalid_or_private_fields_before_http(patch):
    c, _, report = operation_client()
    with pytest.raises(WisdomValidationError):
        c.report_operation_outcome("e1", {**report, **patch})
    assert c.session.calls == []


@pytest.mark.parametrize("field,value", [
    ("org_id", "other"), ("recipient_user_id", "other"), ("event_id", "other"),
    ("outcome", {"request_id": str(uuid4()), "operation_key": "sha256:" + "a" * 64,
        "operation": "install", "state": "completed"}),
])
def test_operation_outcome_rejects_misbound_responses(field, value):
    c, body, report = operation_client()
    c.session.response = Response(200, {**body, field: value})
    with pytest.raises(WisdomError, match="does not match"):
        c.report_operation_outcome("e1", report)


def test_operation_outcome_rechecks_account_after_request():
    c, _, report = operation_client()
    original = c.session.request

    def change_identity(*args, **kwargs):
        c.identity["owner"] = "other"
        return original(*args, **kwargs)

    c.session.request = change_identity
    with pytest.raises(WisdomError, match="does not match"):
        c.report_operation_outcome("e1", report)


@pytest.mark.parametrize("patch", [{"attestation": "verified"}, {"duplicate": 1}, {"advice": "unexpected"}])
def test_operation_outcome_rejects_untrusted_response_claims(patch):
    c, body, report = operation_client()
    c.session.response = Response(200, {**body, **patch})
    with pytest.raises(WisdomError, match="schema validation"):
        c.report_operation_outcome("e1", report)


@pytest.mark.parametrize("operation,state", [
    ("share", "queued"), ("share", "failed"), ("publish", "completed"),
    ("install", "completed"), ("update", "completed"), ("update", "needs_review"),
    ("install", "stale"), ("publish", "expired"),
])
def test_operation_outcome_preserves_exact_result_without_implying_verification(operation, state):
    c, body, report = operation_client()
    report = {**report, "operation": operation, "state": state}
    c.session.response = Response(200, {**body, "outcome": report})
    result = c.report_operation_outcome("e1", report)
    assert result.outcome.model_dump() == report


@pytest.mark.parametrize("field,value", [
    ("org_id", "other-org"), ("recipient_user_id", "other-user"),
    ("request_id", str(uuid4())),
    ("reference", {"kind": "candidate", "key": "sha256:" + "b" * 64}),
])
def test_delivery_claim_rejects_misbound_responses(field, value):
    c, body = delivery_client()
    request = {"request_id": body["request_id"], "reference": body["reference"]}
    c.session.response = Response(200, {**body, field: value})
    with pytest.raises(WisdomError, match="does not match"):
        c.claim_notification_delivery(**request)


@pytest.mark.parametrize("overrides", [
    {"lease_until": None}, {"lease_until": "2026-09-07T12:02:00"},
    {"lease_until": "invalid"}, {"reason": "recipient_muted"},
    {"state": "deferred"}, {"state": "acknowledged"},
    {"untrusted_payload": "not part of this contract"},
])
def test_delivery_claim_rejects_inconsistent_directives(overrides):
    c, body = delivery_client(**overrides)
    with pytest.raises(WisdomError, match="schema validation"):
        c.claim_notification_delivery(body["request_id"], body["reference"])


def test_delivery_response_rechecks_identity_after_request():
    c, body = delivery_client()
    original = c.session.request

    def change_identity(*args, **kwargs):
        c.identity["owner"] = "other-user"
        return original(*args, **kwargs)

    c.session.request = change_identity
    with pytest.raises(WisdomError, match="does not match"):
        c.claim_notification_delivery(body["request_id"], body["reference"])


def test_settlement_sends_only_hashed_receipt_identifiers():
    c, body = delivery_client(state="acknowledged", lease_until=None)
    receipt = DeliveryReceipt(platform="slack", destination="private-channel", message_id="123.456",
        thread_id="100.200", scope_id="private-workspace", acknowledgement="provider_accepted")
    result = c.settle_notification_delivery(body["event_id"], body["request_id"], body["reference"], outcome="acknowledged", receipt=receipt)
    assert result.state == "acknowledged"
    sent = c.session.calls[0][2]["json"]
    assert sent == {"request_id": body["request_id"], "outcome": "acknowledged", "receipt": receipt_projection(receipt).model_dump()}
    serialized = json.dumps(sent)
    for private in [receipt.destination, receipt.message_id, receipt.thread_id, receipt.scope_id]:
        assert private not in serialized
    assert receipt_projection(receipt) == receipt_projection(receipt)
    assert receipt_projection(receipt).message_key != receipt_projection(receipt).destination_key
    changed = receipt.model_copy(update={"scope_id": "different-workspace"})
    assert receipt_projection(changed).message_key != receipt_projection(receipt).message_key


@pytest.mark.parametrize("outcome", ["not_sent", "uncertain"])
def test_settlement_without_send_never_fabricates_a_receipt(outcome):
    c, body = delivery_client(state=outcome, lease_until=None)
    c.settle_notification_delivery(body["event_id"], body["request_id"], body["reference"], outcome=outcome)
    assert c.session.calls[0][2]["json"] == {"request_id": body["request_id"], "outcome": outcome}


def test_settlement_requires_a_valid_receipt_and_matching_result():
    c, body = delivery_client(state="acknowledged", lease_until=None)
    args = (body["event_id"], body["request_id"], body["reference"])
    with pytest.raises(WisdomValidationError):
        c.settle_notification_delivery(*args, outcome="acknowledged")
    with pytest.raises(WisdomValidationError):
        c.settle_notification_delivery(*args, outcome="acknowledged", receipt={"success": True})
    assert c.session.calls == []
    with pytest.raises(WisdomError, match="was not acknowledged"):
        c.settle_notification_delivery(*args, outcome="not_sent")
    c.session.response = Response(200, {**body, "event_id": "other-event", "state": "not_sent"})
    with pytest.raises(WisdomError, match="does not match"):
        c.settle_notification_delivery(*args, outcome="not_sent")


def test_capability_uses_gateway_features_field():
    value = client(Response(200, {"features": ["personal", "org", "wisdom"]}))

    assert value.capability()["features"][-1] == "wisdom"


def _agent_led_policy(**overrides):
    return {
        "org_id": "o1",
        "usage_evidence_window_days": 7,
        "min_aggregate_invocations": 3,
        "consecutive_day_usage_counts": True,
        "repeated_edits_count": True,
        "max_recommendations_per_user_per_week": 3,
        "publication_mode": "moderated",
        "install_popularity_threshold": 10,
        "notification_defaults": {
            "skill_ready_to_share": True,
            "teammate_published": False,
            "update_available": True,
        },
        "manager_review_email_cadence": "daily",
        "not_now_suppression_days": 30,
        "version": 1,
        "updated_by_user_id": None,
        **overrides,
    }


def test_agent_led_policy_reads_member_endpoint_with_bounded_request():
    value = client(Response(200, _agent_led_policy()))
    value.identity = {"claims": {"org_id": "o1"}}
    result = value.agent_led_policy()
    assert result.notification_defaults.teammate_published is False
    assert value.session.calls == [
        (
            "GET",
            "https://gateway.example/v1/sync/wisdom/agent-led/policy",
            {
                "json": None,
                "params": None,
                "timeout": 7,
            },
        )
    ]


@pytest.mark.parametrize(
    "override",
    [
        {"org_id": "other-org"},
        {"min_aggregate_invocations": "3"},
        {"notification_defaults": {"teammate_published": True}},
        {"max_recommendations_per_user_per_week": -1},
    ],
)
def test_agent_led_policy_rejects_wrong_org_or_invalid_response(override):
    value = client(Response(200, _agent_led_policy(**override)))
    value.identity = {"claims": {"org_id": "o1"}}
    with pytest.raises(WisdomError):
        value.agent_led_policy()


@pytest.mark.parametrize("status", [401, 403, 404, 503])
def test_unavailable_agent_led_policy_defers_instead_of_enabling_defaults(
    monkeypatch, status
):
    from hermes_wisdom.agent_led.policy import load_policy

    monkeypatch.setattr("hermes_wisdom.mediation.delivery_mode", lambda: "agent")
    value = client(Response(status, {"error": "unavailable"}))
    value.identity = {"claims": {"org_id": "o1"}}
    result = load_policy(client=value, local={"enabled": True})
    assert result.enabled is False
    assert result.source == "server_unavailable"


def test_fixed_mode_does_not_fetch_agent_led_policy(monkeypatch):
    from hermes_wisdom.agent_led.policy import load_policy

    monkeypatch.setattr("hermes_wisdom.mediation.delivery_mode", lambda: "fixed")
    value = client(Response(200, _agent_led_policy()))
    value.identity = {"claims": {"org_id": "o1"}}
    assert load_policy(client=value, local={"enabled": True}).enabled is False
    assert not value.session.calls


def test_suppression_wire_contains_only_opaque_keys_and_empty_write_body():
    key = "sha256:" + "a" * 64
    value = client(
        Response(
            200, {"org_id": "o1", "key": key, "suppress_until": "2026-10-01T00:00:00Z"}
        )
    )
    value.identity = {"claims": {"org_id": "o1"}}
    assert value.suppress_recommendation(key).key == key
    assert value.session.calls[0][2]["json"] == {}
    assert value.session.calls[0][1].endswith("/suppressions/sha256%3A" + "a" * 64)
    value.session.response = Response(200, {"org_id": "o1", "suppressions": []})
    assert value.recommendation_suppressions([key]) == []
    assert value.session.calls[-1][2]["json"] == {"keys": [key]}


def test_suppression_response_cannot_inject_unrequested_or_foreign_keys():
    key = "sha256:" + "a" * 64
    value = client(
        Response(
            200,
            {
                "org_id": "o1",
                "suppressions": [
                    {
                        "key": "sha256:" + "b" * 64,
                        "suppress_until": "2026-10-01T00:00:00Z",
                    }
                ],
            },
        )
    )
    value.identity = {"claims": {"org_id": "o1"}}
    with pytest.raises(WisdomError):
        value.recommendation_suppressions([key])
    value.session.response = Response(200, {"org_id": "other", "suppressions": []})
    with pytest.raises(WisdomError):
        value.recommendation_suppressions([key])


def test_mute_wire_preserves_native_duration_vocabulary():
    value = client(
        Response(
            200,
            {
                "org_id": "o1",
                "muted": True,
                "duration": "1_week",
                "muted_until": "2026-10-01T00:00:00Z",
                "forever": False,
            },
        )
    )
    value.identity = {"claims": {"org_id": "o1"}}
    assert value.set_recommendation_mute("1_week").muted
    assert value.session.calls[-1][2]["json"] == {"duration": "1_week"}
    with pytest.raises(WisdomValidationError):
        value.set_recommendation_mute("arbitrary")
    value.recommendation_mute()
    assert value.session.calls[-1][2]["params"] == {"include_revision": "1"}


def test_guarded_mute_clear_keeps_idempotency_metadata_on_put():
    response = {"org_id": "o1", "muted": False, "duration": None, "muted_until": None,
                "forever": False, "revision": 3, "mutation_id": "a" * 32, "updated_at": "2026-09-07T00:00:00.000Z"}
    value = client(Response(200, response))
    value.identity = {"claims": {"org_id": "o1"}}
    result = value.set_recommendation_mute(None, expected_revision=2, mutation_id="a" * 32, requested_at="2026-09-07T00:00:00.000Z")
    assert result.revision == 3
    method, _, request = value.session.calls[-1]
    assert method == "PUT"
    assert request["json"] == {"duration": None, "expected_revision": 2, "mutation_id": "a" * 32, "requested_at": "2026-09-07T00:00:00.000Z"}
    with pytest.raises(WisdomValidationError):
        value.set_recommendation_mute("1_day", expected_revision=2)
    assert len(value.session.calls) == 1


def test_submit_body_has_no_local_candidate_or_activity_signals():
    body = {
        "draft": {
            "id": "d1",
            "orgId": "o1",
            "ownerUserId": "u1",
            "slug": "my-skill",
            "draftCommit": "sha256:" + "a" * 64,
            "contentHash": "sha256:" + "b" * 64,
            "authorDescription": "Does a task.",
            "authorDescriptionHash": "sha256:" + "c" * 64,
            "state": "ready",
            "packageManifestHash": "sha256:" + "d" * 64,
            "packageManifestSchemaVersion": 1,
            "systemSpec": None,
            "scan": None,
            "scanVerdict": "pass",
            "explanation": None,
            "updatedAt": "now",
        }
    }
    value = client(Response(201, body))
    value.submit_draft(
        slug="my-skill",
        commit="sha256:" + "a" * 64,
        content_hash="sha256:" + "b" * 64,
        description="Does a task.",
    )
    payload = value.session.calls[0][2]["json"]
    assert payload == {
        "slug": "my-skill",
        "draft_commit": "sha256:" + "a" * 64,
        "content_hash": "sha256:" + "b" * 64,
        "author_description": "Does a task.",
    }
    assert not (
        {"usage", "refinement", "candidate", "ranking", "stability", "dismissal"}
        & payload.keys()
    )


def test_not_found_is_opaque():
    value = client(Response(404, {"error": "not_found"}))
    with pytest.raises(WisdomNotFound, match="item not found"):
        value._request("GET", "skills/secret")


def test_approve_exact_three_hash_body():
    value = client(Response(200, {"draft": {"id": "invalid"}}))
    with pytest.raises(Exception):
        value.approve("d1", content_hash="c", description_hash="d", manifest_hash="m")
    payload = value.session.calls[0][2]["json"]
    assert payload == {
        "content_hash": "c",
        "author_description_hash": "d",
        "package_manifest_hash": "m",
    }


def test_revise_binds_predecessor_hashes_and_new_private_commit():
    value = client(Response(201, {"draft": _draft(id="d2")}))
    professionalism_review = {
        "schema_version": 1,
        "content_hash": "sha256:" + "f" * 64,
        "author_description_hash": "sha256:" + "9" * 64,
        "status": "pass",
        "summary": "No language or conduct concerns detected.",
        "checks": [],
        "provenance": {
            "kind": "agent_assessed",
            "provider": "codex",
            "model": "gpt-5.6-sol",
        },
        "assessed_at": "2026-09-02T00:00:00Z",
    }

    revised = value.revise_draft(
        "d1",
        commit="sha256:" + "e" * 64,
        content_hash="sha256:" + "f" * 64,
        description="Updated owner copy.",
        expected_content_hash="sha256:" + "b" * 64,
        expected_description_hash="sha256:" + "c" * 64,
        expected_manifest_hash="sha256:" + "d" * 64,
        professionalism_review=professionalism_review,
    )

    assert revised.id == "d2"
    method, url, request = value.session.calls[0]
    assert (method, url) == (
        "POST",
        "https://gateway.example/v1/sync/wisdom/drafts/d1/revise",
    )
    assert request["json"] == {
        "draft_commit": "sha256:" + "e" * 64,
        "content_hash": "sha256:" + "f" * 64,
        "author_description": "Updated owner copy.",
        "expected_content_hash": "sha256:" + "b" * 64,
        "expected_author_description_hash": "sha256:" + "c" * 64,
        "expected_package_manifest_hash": "sha256:" + "d" * 64,
        "professionalism_review": professionalism_review,
    }


def test_content_fetch_is_bound_to_installation_identity_and_takedown_generation():
    skill = b"# Skill\n"
    manifest = b'{"schema_version":1,"name":"skill","requirements":{"hermes":{"minimum_version":"0.1.0"}}}'
    files = [
        ("SKILL.md", "file", skill),
        ("skill.manifest.json", "file", manifest),
    ]
    _records, content_hash = verify_content_files(files)
    value = client(
        Response(
            200,
            {
                "commit": "sha256:" + "a" * 64,
                "content_hash": content_hash,
                "files": [
                    {
                        "path": path,
                        "mode": mode,
                        "hash": "sha256:" + hashlib.sha256(body).hexdigest(),
                        "content_base64": base64.b64encode(body).decode("ascii"),
                    }
                    for path, mode, body in files
                ],
            },
        )
    )

    value.content(
        "skill-1",
        2,
        installation_id="hwi_1234567890123456",
        takedown_generation=7,
    )

    method, url, request = value.session.calls[0]
    assert (method, url) == (
        "GET",
        "https://gateway.example/v1/sync/wisdom/skills/skill-1/versions/2/content",
    )
    assert request["params"] == {
        "installation_id": "hwi_1234567890123456",
        "takedown_generation": 7,
    }


def test_raw_copy_fetches_hash_verified_published_bytes_without_install_state():
    skill = b"# Skill\n"
    manifest = b'{"schema_version":1,"name":"skill","requirements":{"hermes":{"minimum_version":"0.1.0"}}}'
    files = [
        ("SKILL.md", "file", skill),
        ("skill.manifest.json", "file", manifest),
    ]
    _records, content_hash = verify_content_files(files)
    value = client(
        Response(
            200,
            {
                "commit": "sha256:" + "a" * 64,
                "content_hash": content_hash,
                "copy_semantics": "unmanaged_fork",
                "files": [
                    {
                        "path": path,
                        "mode": mode,
                        "hash": "sha256:" + hashlib.sha256(body).hexdigest(),
                        "content_base64": base64.b64encode(body).decode("ascii"),
                    }
                    for path, mode, body in files
                ],
            },
        )
    )

    _response, decoded = value.raw_copy("skill-1", 2)

    assert decoded == files
    method, url, request = value.session.calls[0]
    assert (method, url) == (
        "GET",
        "https://gateway.example/v1/sync/wisdom/skills/skill-1/versions/2/raw",
    )
    assert request["params"] is None


def test_installation_reconciliation_uses_identity_path_and_owned_delete():
    value = client(Response(200, {"installations": []}))
    assert value.installations("hwi_1234567890123456") == []
    method, url, request = value.session.calls[0]
    assert (method, url) == (
        "GET",
        "https://gateway.example/v1/sync/wisdom/installations/hwi_1234567890123456",
    )
    assert request["params"] is None

    value.session.response = Response(
        200,
        {
            "skill_id": "skill-1",
            "installation_id": "hwi_1234567890123456",
            "state": "inactive",
        },
    )
    result = value.deactivate_install("hwi_1234567890123456", "skill-1")
    assert result.state == "inactive"
    assert value.session.calls[1][0:2] == (
        "DELETE",
        "https://gateway.example/v1/sync/wisdom/installations/hwi_1234567890123456/skills/skill-1",
    )


def test_installation_and_feed_responses_are_typed_fail_closed():
    value = client(
        Response(
            200,
            {
                "installations": [
                    {
                        "skill_id": "skill-1",
                        "installed_version": 1,
                        "latest_version": 2,
                        "update_mode": "UNKNOWN",
                        "skill_state": "active",
                        "takedown_generation": 0,
                    }
                ]
            },
        )
    )
    with pytest.raises(WisdomError, match="schema validation"):
        value.installations("hwi_1234567890123456")

    value.session.response = Response(
        200,
        {
            "events": [
                {
                    "event_id": "event-1",
                    "kind": "invented",
                    "skill_id": "skill-1",
                    "version": 2,
                    "takedown_generation": 0,
                    "installation_id": "hwi_1234567890123456",
                    "update_mode": "MANUAL",
                    "occurred_at": "2026-08-24T00:00:00Z",
                }
            ],
            "next_cursor": "cursor-1",
            "has_more": False,
        },
    )
    with pytest.raises(WisdomError, match="schema validation"):
        value.feed(installation_id="hwi_1234567890123456")