@agentunion/kite 1.5.0 → 1.6.0

package/extensions/services/dataclaw/api/identity.py

@@ -0,0 +1,505 @@
+"""
+身份认证 API
+"""
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from core.auth import create_access_token, get_current_agent, require_auth
+from core.database import get_session
+from utils.id_generator import gen_agent_id, gen_api_key, gen_key_id, gen_verify_code, gen_uuid
+from utils.crypto import hash_api_key
+
+router = APIRouter()
+DISC = {"entry": "/.well-known/agent-data-exchange.json", "api_spec": "/v1/openapi.json"}
+
+
+class RegisterRequest(BaseModel):
+    name: str
+    type: str = "custom"
+    description: str = ""
+    callback_url: str = ""
+    contacts: dict = {}
+    request_verification: bool = False
+
+
+class VerifyRequest(BaseModel):
+    agent_id: str
+    code: str
+
+
+class RecoverRequest(BaseModel):
+    contact_type: str
+    contact_value: str
+
+
+class RecoverVerifyRequest(BaseModel):
+    agent_id: str
+    code: str
+
+
+class UpdateProfileRequest(BaseModel):
+    name: Optional[str] = None
+    description: Optional[str] = None
+    callback_url: Optional[str] = None
+
+
+class UpdateContactsRequest(BaseModel):
+    phone: Optional[str] = None
+    email: Optional[str] = None
+
+
+class CreateKeyRequest(BaseModel):
+    name: str = ""
+    permissions: list = ["read", "write"]
+    expires_days: Optional[int] = None
+
+
+@router.post("/register")
+async def register(body: RegisterRequest, session: AsyncSession = Depends(get_session)):
+    row = await session.execute(
+        text("SELECT id FROM agents WHERE name=:n AND status!='deleted' LIMIT 1"), {"n": body.name}
+    )
+    if row.fetchone():
+        raise HTTPException(400, detail={"ok": False, "error": "NAME_TAKEN",
+                                         "message": f"名称 '{body.name}' 已被占用", "_discovery": DISC})
+    agent_id = gen_agent_id()
+    if body.request_verification and body.contacts.get("phone"):
+        await session.execute(
+            text("INSERT INTO agents (id, name, type, description, callback_url, verified, credits, status) "
+                 "VALUES (:id, :name, :type, :desc, :cb, 0, 0.00, 'active')"),
+            {"id": agent_id, "name": body.name, "type": body.type, "desc": body.description, "cb": body.callback_url}
+        )
+        phone = body.contacts["phone"]
+        code = gen_verify_code()
+        expires = datetime.now(timezone.utc) + timedelta(minutes=10)
+        await session.execute(
+            text("INSERT INTO verification_codes (contact_type, contact_value, code, purpose, agent_id, expires_at) "
+                 "VALUES ('phone', :phone, :code, 'register', :aid, :exp)"),
+            {"phone": phone, "code": code, "aid": agent_id, "exp": expires}
+        )
+        await session.commit()
+        return {"ok": True, "data": {"agent_id": agent_id, "status": "pending_verification",
+                                     "verification_sent_to": phone,
+                                     "message": "验证码已发送，请在 10 分钟内完成验证"}, "_discovery": DISC}
+    else:
+        api_key = gen_api_key()
+        key_id = gen_key_id()
+        initial_credits = 100.0
+        await session.execute(
+            text("INSERT INTO agents (id, name, type, description, callback_url, verified, credits, status) "
+                 "VALUES (:id, :name, :type, :desc, :cb, 0, :credits, 'active')"),
+            {"id": agent_id, "name": body.name, "type": body.type, "desc": body.description,
+             "cb": body.callback_url, "credits": initial_credits}
+        )
+        await session.execute(
+            text("INSERT INTO api_keys (id, agent_id, key_hash, key_prefix, name, permissions, status) "
+                 "VALUES (:kid, :aid, :hash, :prefix, 'default', '[\"read\",\"write\"]', 'active')"),
+            {"kid": key_id, "aid": agent_id, "hash": hash_api_key(api_key), "prefix": api_key[:10]}
+        )
+        tid = gen_uuid()[:32]
+        await session.execute(
+            text("INSERT INTO credit_transactions (id, agent_id, type, amount, balance_after, description) "
+                 "VALUES (:tid, :aid, 'bonus', :amt, :bal, '注册奖励')"),
+            {"tid": tid, "aid": agent_id, "amt": initial_credits, "bal": initial_credits}
+        )
+        await session.commit()
+        return {"ok": True, "data": {"agent_id": agent_id, "api_key": api_key,
+                                     "initial_credits": initial_credits, "verified": False,
+                                     "message": f"注册成功，已赠送 {initial_credits} 积分"}, "_discovery": DISC}
+
+
+@router.post("/verify")
+async def verify(body: VerifyRequest, session: AsyncSession = Depends(get_session)):
+    row = (await session.execute(
+        text("SELECT id, expires_at, used FROM verification_codes "
+             "WHERE agent_id=:aid AND code=:code AND purpose='register' ORDER BY created_at DESC LIMIT 1"),
+        {"aid": body.agent_id, "code": body.code}
+    )).fetchone()
+    if not row:
+        raise HTTPException(400, detail={"ok": False, "error": "INVALID_CODE",
+                                         "message": "验证码无效", "_discovery": DISC})
+    if row.used:
+        raise HTTPException(400, detail={"ok": False, "error": "CODE_USED",
+                                         "message": "验证码已使用", "_discovery": DISC})
+    if datetime.now(timezone.utc) > row.expires_at.replace(tzinfo=timezone.utc):
+        raise HTTPException(400, detail={"ok": False, "error": "CODE_EXPIRED",
+                                         "message": "验证码已过期", "_discovery": DISC})
+    await session.execute(
+        text("UPDATE agents SET verified=1 WHERE id=:aid"), {"aid": body.agent_id}
+    )
+    await session.execute(
+        text("UPDATE verification_codes SET used=1 WHERE id=:id"), {"id": row.id}
+    )
+    api_key = gen_api_key()
+    key_id = gen_key_id()
+    await session.execute(
+        text("INSERT INTO api_keys (id, agent_id, key_hash, key_prefix, name, permissions, status) "
+             "VALUES (:kid, :aid, :hash, :prefix, 'default', '[\"read\",\"write\"]', 'active')"),
+        {"kid": key_id, "aid": body.agent_id, "hash": hash_api_key(api_key), "prefix": api_key[:10]}
+    )
+    await session.commit()
+    return {"ok": True, "data": {"agent_id": body.agent_id, "api_key": api_key,
+                                 "verified": True, "message": "验证成功"}, "_discovery": DISC}
+
+
+@router.post("/recover")
+async def recover(body: RecoverRequest, session: AsyncSession = Depends(get_session)):
+    row = (await session.execute(
+        text("SELECT a.id FROM agents a "
+             "JOIN agent_contacts c ON c.agent_id=a.id "
+             "WHERE c.contact_type=:ct AND c.contact_value=:cv AND a.status='active' LIMIT 1"),
+        {"ct": body.contact_type, "cv": body.contact_value}
+    )).fetchone()
+    if not row:
+        raise HTTPException(404, detail={"ok": False, "error": "NOT_FOUND",
+                                          "message": "未找到匹配的账户", "_discovery": DISC})
+    agent_id = row.id
+    code = gen_verify_code()
+    expires = datetime.now(timezone.utc) + timedelta(minutes=10)
+    await session.execute(
+        text("INSERT INTO verification_codes (contact_type, contact_value, code, purpose, agent_id, expires_at) "
+             "VALUES (:ct, :cv, :code, 'recover', :aid, :exp)"),
+        {"ct": body.contact_type, "cv": body.contact_value, "code": code, "aid": agent_id, "exp": expires}
+    )
+    await session.commit()
+    return {"ok": True, "data": {"agent_id": agent_id,
+                                 "message": "验证码已发送，请在 10 分钟内完成验证"}, "_discovery": DISC}
+
+
+@router.post("/recover/verify")
+async def recover_verify(body: RecoverVerifyRequest, session: AsyncSession = Depends(get_session)):
+    row = (await session.execute(
+        text("SELECT id, expires_at, used FROM verification_codes "
+             "WHERE agent_id=:aid AND code=:code AND purpose='recover' ORDER BY created_at DESC LIMIT 1"),
+        {"aid": body.agent_id, "code": body.code}
+    )).fetchone()
+    if not row:
+        raise HTTPException(400, detail={"ok": False, "error": "INVALID_CODE",
+                                         "message": "验证码无效", "_discovery": DISC})
+    if row.used:
+        raise HTTPException(400, detail={"ok": False, "error": "CODE_USED",
+                                         "message": "验证码已使用", "_discovery": DISC})
+    if datetime.now(timezone.utc) > row.expires_at.replace(tzinfo=timezone.utc):
+        raise HTTPException(400, detail={"ok": False, "error": "CODE_EXPIRED",
+                                         "message": "验证码已过期", "_discovery": DISC})
+    await session.execute(
+        text("UPDATE verification_codes SET used=1 WHERE id=:id"), {"id": row.id}
+    )
+    api_key = gen_api_key()
+    key_id = gen_key_id()
+    await session.execute(
+        text("INSERT INTO api_keys (id, agent_id, key_hash, key_prefix, name, permissions, status) "
+             "VALUES (:kid, :aid, :hash, :prefix, 'recovered', '[\"read\",\"write\"]', 'active')"),
+        {"kid": key_id, "aid": body.agent_id, "hash": hash_api_key(api_key), "prefix": api_key[:10]}
+    )
+    await session.commit()
+    return {"ok": True, "data": {"agent_id": body.agent_id, "api_key": api_key,
+                                 "message": "恢复成功，新 API Key 已生成"}, "_discovery": DISC}
+
+
+@router.get("/profile")
+async def get_profile(agent_id: str = Depends(require_auth), session: AsyncSession = Depends(get_session)):
+    row = (await session.execute(
+        text("SELECT id, name, type, description, callback_url, verified, credits, status, created_at "
+             "FROM agents WHERE id=:id"),
+        {"id": agent_id}
+    )).fetchone()
+    if not row:
+        raise HTTPException(404, detail={"ok": False, "error": "NOT_FOUND", "_discovery": DISC})
+    return {"ok": True, "data": {
+        "agent_id": row.id, "name": row.name, "type": row.type,
+        "description": row.description, "callback_url": row.callback_url,
+        "verified": bool(row.verified), "credits": float(row.credits),
+        "status": row.status, "created_at": row.created_at.isoformat()
+    }, "_discovery": DISC}
+
+
+@router.patch("/profile")
+async def update_profile(body: UpdateProfileRequest, agent_id: str = Depends(require_auth),
+                         session: AsyncSession = Depends(get_session)):
+    fields, params = [], {"id": agent_id}
+    if body.name is not None:
+        fields.append("name=:name"); params["name"] = body.name
+    if body.description is not None:
+        fields.append("description=:description"); params["description"] = body.description
+    if body.callback_url is not None:
+        fields.append("callback_url=:callback_url"); params["callback_url"] = body.callback_url
+    if not fields:
+        raise HTTPException(400, detail={"ok": False, "error": "NO_FIELDS",
+                                         "message": "没有提供任何更新字段", "_discovery": DISC})
+    await session.execute(text(f"UPDATE agents SET {', '.join(fields)} WHERE id=:id"), params)
+    await session.commit()
+    return {"ok": True, "data": {"message": "资料已更新"}, "_discovery": DISC}
+
+
+@router.get("/keys")
+async def list_keys(agent_id: str = Depends(require_auth), session: AsyncSession = Depends(get_session)):
+    rows = (await session.execute(
+        text("SELECT id, name, key_prefix, permissions, status, created_at, expires_at, last_used_at "
+             "FROM api_keys WHERE agent_id=:aid AND status!='deleted' ORDER BY created_at DESC"),
+        {"aid": agent_id}
+    )).fetchall()
+    keys = []
+    for r in rows:
+        keys.append({
+            "key_id": r.id, "name": r.name, "key_prefix": r.key_prefix,
+            "permissions": r.permissions, "status": r.status,
+            "created_at": r.created_at.isoformat(),
+            "expires_at": r.expires_at.isoformat() if r.expires_at else None,
+            "last_used_at": r.last_used_at.isoformat() if r.last_used_at else None
+        })
+    return {"ok": True, "data": {"keys": keys, "total": len(keys)}, "_discovery": DISC}
+
+
+@router.post("/keys")
+async def create_key(body: CreateKeyRequest, agent_id: str = Depends(require_auth),
+                     session: AsyncSession = Depends(get_session)):
+    api_key = gen_api_key()
+    key_id = gen_key_id()
+    expires_at = None
+    if body.expires_days:
+        expires_at = datetime.now(timezone.utc) + timedelta(days=body.expires_days)
+    import json
+    await session.execute(
+        text("INSERT INTO api_keys (id, agent_id, key_hash, key_prefix, name, permissions, status, expires_at) "
+             "VALUES (:kid, :aid, :hash, :prefix, :name, :perms, 'active', :exp)"),
+        {"kid": key_id, "aid": agent_id, "hash": hash_api_key(api_key),
+         "prefix": api_key[:10], "name": body.name,
+         "perms": json.dumps(body.permissions), "exp": expires_at}
+    )
+    await session.commit()
+    return {"ok": True, "data": {"key_id": key_id, "api_key": api_key,
+                                 "name": body.name, "permissions": body.permissions,
+                                 "expires_at": expires_at.isoformat() if expires_at else None,
+                                 "message": "API Key 已创建，请妥善保存，此后不再显示完整密钥"}, "_discovery": DISC}
+
+
+class SendCodeRequest(BaseModel):
+    phone: Optional[str] = None
+    email: Optional[str] = None
+    purpose: str = "login"
+
+
+class LoginRequest(BaseModel):
+    phone: Optional[str] = None
+    email: Optional[str] = None
+    code: str = ""
+    api_key: Optional[str] = None
+
+
+@router.post("/send-code")
+async def send_code(body: SendCodeRequest, session: AsyncSession = Depends(get_session)):
+    """发送验证码（手机或邮箱）"""
+    code = gen_verify_code()
+    expires = datetime.now(timezone.utc) + timedelta(minutes=10)
+
+    if body.phone:
+        contact_type, contact_value = "phone", body.phone
+    elif body.email:
+        contact_type, contact_value = "email", body.email
+    else:
+        raise HTTPException(400, detail={"ok": False, "error": "MISSING_CONTACT",
+                                         "message": "请提供手机号或邮箱", "_discovery": DISC})
+
+    # 查找关联的 agent_id（如果存在）
+    agent_id = None
+    row = (await session.execute(
+        text("SELECT agent_id FROM agent_contacts WHERE contact_type=:ct AND contact_value=:cv LIMIT 1"),
+        {"ct": contact_type, "cv": contact_value}
+    )).fetchone()
+    if row:
+        agent_id = row.agent_id
+
+    await session.execute(
+        text("INSERT INTO verification_codes (contact_type, contact_value, code, purpose, agent_id, expires_at) "
+             "VALUES (:ct, :cv, :code, :purpose, :aid, :exp)"),
+        {"ct": contact_type, "cv": contact_value, "code": code,
+         "purpose": body.purpose, "aid": agent_id, "exp": expires}
+    )
+    await session.commit()
+
+    # 尝试实际发送（降级模式下只打印日志）
+    if contact_type == "phone":
+        try:
+            from services.sms_service import send_verification_code
+            await send_verification_code(body.phone, code)
+        except Exception as e:
+            print(f"[dataclaw] send sms failed: {e}")
+    elif contact_type == "email":
+        try:
+            from services.email_service import send_verification_email
+            await send_verification_email(body.email, code)
+        except Exception as e:
+            print(f"[dataclaw] send email failed: {e}")
+
+    return {"ok": True, "data": {"message": "验证码已发送", "expires_in": 600,
+                                  "contact": contact_value}, "_discovery": DISC}
+
+
+@router.post("/login")
+async def login(body: LoginRequest, session: AsyncSession = Depends(get_session)):
+    """通过手机号/邮箱 + 验证码登录"""
+    if body.api_key:
+        # API Key 直接登录
+        from utils.crypto import hash_api_key
+        key_hash = hash_api_key(body.api_key)
+        row = (await session.execute(
+            text("SELECT agent_id FROM api_keys WHERE key_hash=:h AND status='active' LIMIT 1"),
+            {"h": key_hash}
+        )).fetchone()
+        if not row:
+            raise HTTPException(401, detail={"ok": False, "error": "INVALID_KEY",
+                                              "message": "API Key 无效", "_discovery": DISC})
+        token = create_access_token(row.agent_id)
+        return {"ok": True, "data": {"agent_id": row.agent_id, "token": token,
+                                      "api_key": body.api_key}, "_discovery": DISC}
+
+    # 验证码登录
+    if body.phone:
+        contact_type, contact_value = "phone", body.phone
+    elif body.email:
+        contact_type, contact_value = "email", body.email
+    else:
+        raise HTTPException(400, detail={"ok": False, "error": "MISSING_CONTACT",
+                                         "message": "请提供手机号或邮箱", "_discovery": DISC})
+
+    if not body.code:
+        raise HTTPException(400, detail={"ok": False, "error": "MISSING_CODE",
+                                         "message": "请输入验证码", "_discovery": DISC})
+
+    # 验证码校验
+    code_row = (await session.execute(
+        text("SELECT id, agent_id, expires_at, used FROM verification_codes "
+             "WHERE contact_type=:ct AND contact_value=:cv AND code=:code AND used=0 "
+             "ORDER BY created_at DESC LIMIT 1"),
+        {"ct": contact_type, "cv": contact_value, "code": body.code}
+    )).fetchone()
+    if not code_row:
+        raise HTTPException(400, detail={"ok": False, "error": "INVALID_CODE",
+                                         "message": "验证码无效", "_discovery": DISC})
+    if datetime.now(timezone.utc) > code_row.expires_at.replace(tzinfo=timezone.utc):
+        raise HTTPException(400, detail={"ok": False, "error": "CODE_EXPIRED",
+                                         "message": "验证码已过期", "_discovery": DISC})
+
+    # 标记验证码已使用
+    await session.execute(
+        text("UPDATE verification_codes SET used=1 WHERE id=:id"), {"id": code_row.id}
+    )
+
+    agent_id = code_row.agent_id
+    if not agent_id:
+        # 查找联系方式关联的 agent
+        contact = (await session.execute(
+            text("SELECT agent_id FROM agent_contacts WHERE contact_type=:ct AND contact_value=:cv LIMIT 1"),
+            {"ct": contact_type, "cv": contact_value}
+        )).fetchone()
+        if contact:
+            agent_id = contact.agent_id
+
+    if not agent_id:
+        # 自动注册新 agent
+        agent_id = gen_agent_id()
+        initial_credits = 100.0
+        name = f"{contact_type}_{contact_value[-4:]}"
+        await session.execute(
+            text("INSERT INTO agents (id, name, type, description, verified, credits, status) "
+                 "VALUES (:id, :name, 'custom', :desc, 1, :credits, 'active')"),
+            {"id": agent_id, "name": name, "desc": f"通过{contact_type}注册", "credits": initial_credits}
+        )
+        await session.execute(
+            text("INSERT INTO agent_contacts (agent_id, contact_type, contact_value, verified) "
+                 "VALUES (:aid, :ct, :cv, 1)"),
+            {"aid": agent_id, "ct": contact_type, "cv": contact_value}
+        )
+        # 创建 API Key
+        api_key = gen_api_key()
+        key_id = gen_key_id()
+        await session.execute(
+            text("INSERT INTO api_keys (id, agent_id, key_hash, key_prefix, name, permissions, status) "
+                 "VALUES (:kid, :aid, :hash, :prefix, 'login_default', '[\"read\",\"write\"]', 'active')"),
+            {"kid": key_id, "aid": agent_id, "hash": hash_api_key(api_key), "prefix": api_key[:10]}
+        )
+        tid = gen_uuid()[:32]
+        await session.execute(
+            text("INSERT INTO credit_transactions (id, agent_id, type, amount, balance_after, description) "
+                 "VALUES (:tid, :aid, 'bonus', :amt, :bal, '注册奖励')"),
+            {"tid": tid, "aid": agent_id, "amt": initial_credits, "bal": initial_credits}
+        )
+
+    await session.commit()
+    token = create_access_token(agent_id)
+    return {"ok": True, "data": {"agent_id": agent_id, "token": token,
+                                  "message": "登录成功"}, "_discovery": DISC}
+
+
+@router.get("/oauth/{provider}/authorize")
+async def oauth_authorize(provider: str):
+    """OAuth 授权跳转"""
+    from fastapi.responses import RedirectResponse
+    if provider == "github":
+        from services.oauth_service import get_github_authorize_url
+        url = get_github_authorize_url(f"/v1/identity/oauth/github/callback")
+        if not url:
+            raise HTTPException(503, detail={"ok": False, "error": "OAUTH_NOT_CONFIGURED",
+                                              "message": "GitHub OAuth 未配置", "_discovery": DISC})
+        return RedirectResponse(url)
+    elif provider == "google":
+        from services.oauth_service import get_google_authorize_url
+        url = get_google_authorize_url(f"/v1/identity/oauth/google/callback")
+        if not url:
+            raise HTTPException(503, detail={"ok": False, "error": "OAUTH_NOT_CONFIGURED",
+                                              "message": "Google OAuth 未配置", "_discovery": DISC})
+        return RedirectResponse(url)
+    else:
+        raise HTTPException(400, detail={"ok": False, "error": "UNSUPPORTED_PROVIDER",
+                                          "message": f"不支持的 OAuth 提供商: {provider}", "_discovery": DISC})
+
+
+@router.get("/oauth/{provider}/callback")
+async def oauth_callback(provider: str, code: str = "", session: AsyncSession = Depends(get_session)):
+    """OAuth 回调处理"""
+    from fastapi.responses import RedirectResponse
+    if not code:
+        return RedirectResponse("/login?error=oauth_failed")
+
+    user_info = None
+    if provider == "github":
+        from services.oauth_service import exchange_github_code
+        user_info = await exchange_github_code(code, f"/v1/identity/oauth/github/callback")
+    elif provider == "google":
+        from services.oauth_service import exchange_google_code
+        user_info = await exchange_google_code(code, f"/v1/identity/oauth/google/callback")
+
+    if not user_info:
+        return RedirectResponse("/login?error=oauth_failed")
+
+    from services.oauth_service import find_or_create_agent_by_oauth
+    agent_id, is_new = await find_or_create_agent_by_oauth(provider, user_info, session)
+
+    # 生成 JWT token
+    token = create_access_token(agent_id)
+
+    # 重定向到前端并携带 token
+    return RedirectResponse(f"/dashboard?oauth_token={token}&provider={provider}&new={'1' if is_new else '0'}")
+
+
+@router.delete("/keys/{key_id}")
+async def delete_key(key_id: str, agent_id: str = Depends(require_auth),
+                     session: AsyncSession = Depends(get_session)):
+    row = (await session.execute(
+        text("SELECT id FROM api_keys WHERE id=:kid AND agent_id=:aid AND status!='deleted'"),
+        {"kid": key_id, "aid": agent_id}
+    )).fetchone()
+    if not row:
+        raise HTTPException(404, detail={"ok": False, "error": "NOT_FOUND",
+                                          "message": "Key 不存在", "_discovery": DISC})
+    await session.execute(
+        text("UPDATE api_keys SET status='deleted' WHERE id=:kid"), {"kid": key_id}
+    )
+    await session.commit()
+    return {"ok": True, "data": {"message": "API Key 已吊销"}, "_discovery": DISC}

package/extensions/services/dataclaw/api/notifications.py

@@ -0,0 +1,104 @@
+"""
+通知系统 API
+"""
+from typing import Optional
+
+from fastapi import APIRouter, Depends, Query
+from pydantic import BaseModel
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from core.auth import require_auth
+from core.database import get_session
+from utils.id_generator import gen_notif_id
+
+router = APIRouter()
+DISC = {"entry": "/.well-known/agent-data-exchange.json"}
+
+
+@router.get("")
+async def list_notifications(
+    unread_only: bool = Query(False),
+    limit: int = Query(50, ge=1, le=200),
+    offset: int = Query(0, ge=0),
+    agent_id: str = Depends(require_auth),
+    session: AsyncSession = Depends(get_session)
+):
+    conditions = ["agent_id=:aid"]
+    params = {"aid": agent_id, "lim": limit, "off": offset}
+    if unread_only:
+        conditions.append("read_at IS NULL")
+    where = " AND ".join(conditions)
+    rows = (await session.execute(
+        text(f"SELECT id, type, title, content, link, read_at, created_at "
+             f"FROM notifications WHERE {where} ORDER BY created_at DESC LIMIT :lim OFFSET :off"),
+        params
+    )).fetchall()
+    total = (await session.execute(
+        text(f"SELECT COUNT(*) FROM notifications WHERE {where}"),
+        {k: v for k, v in params.items() if k not in ('lim', 'off')}
+    )).scalar()
+    notifs = [
+        {
+            "id": r.id, "type": r.type, "title": r.title,
+            "content": r.content, "link": r.link,
+            "read": r.read_at is not None,
+            "created_at": r.created_at.isoformat() if r.created_at else None
+        }
+        for r in rows
+    ]
+    return {"ok": True, "data": {"notifications": notifs, "total": total,
+                                  "limit": limit, "offset": offset}, "_discovery": DISC}
+
+
+@router.get("/unread")
+async def get_unread_count(
+    agent_id: str = Depends(require_auth),
+    session: AsyncSession = Depends(get_session)
+):
+    count = (await session.execute(
+        text("SELECT COUNT(*) FROM notifications WHERE agent_id=:aid AND read_at IS NULL"),
+        {"aid": agent_id}
+    )).scalar()
+    return {"ok": True, "data": {"unread_count": count}, "_discovery": DISC}
+
+
+@router.post("/read-all")
+async def mark_all_read(
+    agent_id: str = Depends(require_auth),
+    session: AsyncSession = Depends(get_session)
+):
+    result = await session.execute(
+        text("UPDATE notifications SET read_at=NOW() WHERE agent_id=:aid AND read_at IS NULL"),
+        {"aid": agent_id}
+    )
+    await session.commit()
+    return {"ok": True, "data": {"updated": result.rowcount}, "_discovery": DISC}
+
+
+@router.post("/{notif_id}/read")
+async def mark_read(
+    notif_id: str,
+    agent_id: str = Depends(require_auth),
+    session: AsyncSession = Depends(get_session)
+):
+    await session.execute(
+        text("UPDATE notifications SET read_at=NOW() WHERE id=:nid AND agent_id=:aid"),
+        {"nid": notif_id, "aid": agent_id}
+    )
+    await session.commit()
+    return {"ok": True, "data": {"id": notif_id}, "_discovery": DISC}
+
+
+@router.delete("/{notif_id}")
+async def delete_notification(
+    notif_id: str,
+    agent_id: str = Depends(require_auth),
+    session: AsyncSession = Depends(get_session)
+):
+    await session.execute(
+        text("DELETE FROM notifications WHERE id=:nid AND agent_id=:aid"),
+        {"nid": notif_id, "aid": agent_id}
+    )
+    await session.commit()
+    return {"ok": True, "data": {"deleted": notif_id}, "_discovery": DISC}