AiMaintenance - BevvyTech/BrewskiDocs GitHub Wiki

AI Maintenance Endpoints

Overview

  • Endpoint Group: AI / Maintenance
  • Purpose: Inspect AI tool executions for a chat session and reset session history when required.
  • Availability: Requires authentication. Only the session owner or members of the same team (including super-user operators) may access these endpoints.

Endpoint Summary

Method Path Description
GET /ai/logs Return the most recent AI action log entries for a chat session.
DELETE /ai/sessions Clear the active AI session for the requesting user/team (retains hidden history).

Authentication

  • Authorization: Bearer <token> header is required.
  • Callers must be either:
    • the owner of the session (session.userId matches the current user), or
    • an active member of the same team as the session owner, or
    • a super-user (team.role === "su").
  • All other callers receive 403 Forbidden.

GET /ai/logs

Query Parameters

Name Type Required Notes
sessionId uuid ✅ Target AI session.
limit integer (1–200) ➖ Defaults to 50. Results are returned newest first.

Response 200 OK 

{
  "sessionId": "a63ab83d-2bb8-42ab-8374-23b8e1e276e3",
  "count": 3,
  "logs": [
    {
      "id": "a9d95feb-671a-4cac-9c2b-7db02e106b13",
      "type": "navigate",
      "success": true,
      "createdAt": "2025-06-20T11:58:41.123Z",
      "payload": {
        "route": "/beers/c7d0c5bc-8ab5-41fb-adb4-1a594d5d2177"
      }
    },
    {
      "id": "6efadf60-5f09-4301-975b-01978f19bc5c",
      "type": "search_clients",
      "success": true,
      "createdAt": "2025-06-20T11:58:35.441Z",
      "payload": {
        "query": "Lantern",
        "results": 5
      }
    }
  ]
}

Error Codes

Status Body Example When It Happens
400 Bad Request { "message": "Invalid request" } sessionId missing/invalid or limit outside range.
401 Unauthorized { "message": "Unauthorized" } Token missing or expired.
403 Forbidden { "message": "Forbidden" } Caller lacks access to the target session.
404 Not Found { "message": "Session not found" } sessionId does not exist.

Side Effects & Notes

  • Read-only; no database writes occur.
  • Logs are sorted newest → oldest and include the persisted payload stored in AiActionLog.payload.
  • Use limit < 50 to minimise payload sizes when polling.

DELETE /ai/sessions

Existing behaviour retained here for completeness—this endpoint clears the current user's session for a team and triggers a WebSocket reset.

Query Parameters

Name Type Required Notes
teamId uuid ✅ Team that owns the session.
userId uuid ✅ Must match the authenticated user.

Response 204 No Content

  • Hides all user messages, deletes assistant/tool messages, wipes action logs, and resets lastMessageAt for the session.

Error Codes

Status Body Example When It Happens
400 Bad Request { "message": "Invalid request" } Missing/invalid parameters.
401 Unauthorized { "message": "Unauthorized" } Token missing or expired.
403 Forbidden { "message": "Forbidden" } Provided userId does not match the caller, or caller lacks membership.

Side Effects & Notes

  • Runs inside a transaction: either all AI messages/logs for the session are cleared or nothing changes.
  • After completion, the websocket registry is notified so the next message starts a fresh session turn.

Changelog

Date Author Change
2025-10-22 AI Agent Documented /ai/logs and /ai/sessions.
⚠️ **GitHub.com Fallback** ⚠️