thumbgate 1.29.1 → 1.29.2

package/config/schemas/task-outcome-receipt.schema.json

@@ -0,0 +1,296 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://thumbgate.ai/schemas/task-outcome-receipt.schema.json",
+  "title": "ThumbGate Task Outcome Receipt",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "taskId",
+    "taskType",
+    "goal",
+    "status",
+    "verification",
+    "toolCalls",
+    "policy",
+    "efficiency"
+  ],
+  "properties": {
+    "taskId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200
+    },
+    "taskType": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 100
+    },
+    "goal": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2000
+    },
+    "expectedOutcome": {
+      "type": "string",
+      "maxLength": 2000
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "completed",
+        "failed",
+        "partial",
+        "escalated"
+      ]
+    },
+    "verification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "performed",
+        "passed",
+        "evidence"
+      ],
+      "properties": {
+        "performed": {
+          "type": "boolean"
+        },
+        "passed": {
+          "type": "boolean"
+        },
+        "verifier": {
+          "type": "string",
+          "maxLength": 200
+        },
+        "method": {
+          "type": "string",
+          "maxLength": 200
+        },
+        "evidence": {
+          "type": "array",
+          "maxItems": 100,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000
+          }
+        },
+        "unsupportedClaims": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "toolCalls": {
+      "type": "array",
+      "maxItems": 1000,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "name",
+          "contractValid",
+          "allowed",
+          "succeeded",
+          "attempts"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          },
+          "contractValid": {
+            "type": "boolean"
+          },
+          "allowed": {
+            "type": "boolean"
+          },
+          "succeeded": {
+            "type": "boolean"
+          },
+          "attempts": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "latencyMs": {
+            "type": "number",
+            "minimum": 0
+          },
+          "costUsd": {
+            "type": "number",
+            "minimum": 0
+          },
+          "sideEffect": {
+            "type": "boolean"
+          },
+          "idempotencyKey": {
+            "type": "string",
+            "maxLength": 300
+          },
+          "duplicateSideEffect": {
+            "type": "boolean"
+          }
+        }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "violations",
+        "unsafeEscapes",
+        "falseBlocks"
+      ],
+      "properties": {
+        "violations": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "unsafeEscapes": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "falseBlocks": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "category": {
+          "type": "string",
+          "maxLength": 200
+        },
+        "recovered": {
+          "type": "boolean"
+        },
+        "repeated": {
+          "type": "boolean"
+        },
+        "rolledBack": {
+          "type": "boolean"
+        }
+      }
+    },
+    "escalation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "required": {
+          "type": "boolean"
+        },
+        "correct": {
+          "type": "boolean"
+        },
+        "escalationId": {
+          "type": "string",
+          "maxLength": 200
+        }
+      }
+    },
+    "efficiency": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "latencyMs",
+        "costUsd"
+      ],
+      "properties": {
+        "latencyMs": {
+          "type": "number",
+          "minimum": 0
+        },
+        "costUsd": {
+          "type": "number",
+          "minimum": 0
+        },
+        "firstAttempt": {
+          "type": "boolean"
+        }
+      }
+    },
+    "businessOutcome": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kpi",
+        "value",
+        "unit"
+      ],
+      "properties": {
+        "kpi": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "value": {
+          "type": "number"
+        },
+        "unit": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 50
+        }
+      }
+    },
+    "traceId": {
+      "type": "string",
+      "maxLength": 200
+    },
+    "idempotencyKey": {
+      "type": "string",
+      "maxLength": 300
+    },
+    "versions": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "model": {
+          "type": "string",
+          "maxLength": 200
+        },
+        "prompt": {
+          "type": "string",
+          "maxLength": 200
+        },
+        "tools": {
+          "type": "string",
+          "maxLength": 200
+        },
+        "policy": {
+          "type": "string",
+          "maxLength": 200
+        },
+        "release": {
+          "type": "string",
+          "maxLength": 200
+        }
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "recordedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "receiptHash": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "working": {
+      "type": "boolean"
+    },
+    "workingReasons": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

package/openapi/openapi.yaml

@@ -19,6 +19,11 @@ components:
       type: http
       scheme: bearer
       bearerFormat: API Key
+    humanReviewerKey:
+      type: apiKey
+      in: header
+      name: X-ThumbGate-Human-Reviewer-Key
+      description: Independently revocable credential for the server-configured human reviewer identity.
   schemas:
     RubricScore:
       type: object
@@ -77,6 +82,135 @@ components:
           enum: [chatgpt_gpt]
           default: chatgpt_gpt
           description: Attribution marker for ThumbGate analytics. The published ThumbGate GPT should send `chatgpt_gpt` so owner dashboards can distinguish GPT Action calls from local API calls.
+    TaskOutcomeReceipt:
+      type: object
+      additionalProperties: false
+      required: [taskId, goal, status, verification, toolCalls, policy, efficiency]
+      properties:
+        taskId:
+          type: string
+        taskType:
+          type: string
+        goal:
+          type: string
+        expectedOutcome:
+          type: string
+        status:
+          type: string
+          enum: [completed, failed, partial, escalated]
+        verification:
+          type: object
+          required: [performed, passed, evidence]
+          properties:
+            performed:
+              type: boolean
+            passed:
+              type: boolean
+            verifier:
+              type: string
+            method:
+              type: string
+            evidence:
+              type: array
+              items:
+                type: string
+            unsupportedClaims:
+              type: integer
+              minimum: 0
+        toolCalls:
+          type: array
+          items:
+            type: object
+            required: [name, contractValid, allowed, succeeded, attempts]
+            properties:
+              name:
+                type: string
+              contractValid:
+                type: boolean
+              allowed:
+                type: boolean
+              succeeded:
+                type: boolean
+              attempts:
+                type: integer
+                minimum: 1
+              idempotencyKey:
+                type: string
+              duplicateSideEffect:
+                type: boolean
+        policy:
+          type: object
+          required: [violations, unsafeEscapes, falseBlocks]
+          properties:
+            violations:
+              type: integer
+            unsafeEscapes:
+              type: integer
+            falseBlocks:
+              type: integer
+        efficiency:
+          type: object
+          required: [latencyMs, costUsd]
+          properties:
+            latencyMs:
+              type: number
+            costUsd:
+              type: number
+            firstAttempt:
+              type: boolean
+        idempotencyKey:
+          type: string
+    EscalationIdentity:
+      type: object
+      additionalProperties: false
+      required: [id, kind]
+      properties:
+        id:
+          type: string
+          minLength: 1
+        kind:
+          type: string
+          enum: [agent, service, human]
+        displayName:
+          type: string
+    HumanEscalationRequest:
+      type: object
+      additionalProperties: false
+      required: [taskId, reason, requester, evidence]
+      properties:
+        taskId:
+          type: string
+          minLength: 1
+        reason:
+          type: string
+          minLength: 1
+        severity:
+          type: string
+          enum: [low, medium, high, critical]
+        requester:
+          $ref: '#/components/schemas/EscalationIdentity'
+        evidence:
+          type: array
+          minItems: 1
+          items:
+            type: string
+            minLength: 1
+        ttlMs:
+          type: number
+          minimum: 1
+        idempotencyKey:
+          type: string
+    HumanEscalationDecision:
+      type: object
+      additionalProperties: false
+      required: [decision, reason]
+      properties:
+        decision:
+          type: string
+          enum: [approved, rejected, cancelled]
+        reason:
+          type: string
+          minLength: 1
     IntentPlanRequest:
       type: object
       required: [intentId]
@@ -1940,3 +2074,104 @@ paths:
           description: Invalid PayPal transmission headers, event, or remote signature verification
         '503':
           description: PayPal verified the event but durable evidence storage failed
+  /v1/task-outcomes:
+    post:
+      operationId: recordTaskOutcome
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TaskOutcomeReceipt'
+      responses:
+        '201':
+          description: Task outcome recorded
+        '400':
+          description: Invalid or conflicting task outcome
+        '401':
+          description: Unauthorized
+    get:
+      operationId: listTaskOutcomes
+      parameters:
+        - in: query
+          name: taskId
+          schema:
+            type: string
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            default: 20
+      responses:
+        '200':
+          description: Task outcomes
+        '401':
+          description: Unauthorized
+  /v1/task-outcomes/metrics:
+    get:
+      operationId: getTaskOutcomeMetrics
+      responses:
+        '200':
+          description: Transparent task, tool, safety, escalation, cost, latency, and business metrics
+        '401':
+          description: Unauthorized
+  /v1/task-outcomes/monitor:
+    get:
+      operationId: monitorTaskOutcomes
+      responses:
+        '200':
+          description: Production task outcome threshold verdict
+        '401':
+          description: Unauthorized
+  /v1/escalations:
+    post:
+      operationId: requestHumanEscalation
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/HumanEscalationRequest'
+      responses:
+        '201':
+          description: Human escalation requested
+        '400':
+          description: Invalid or conflicting request
+        '401':
+          description: Unauthorized
+    get:
+      operationId: listHumanEscalations
+      responses:
+        '200':
+          description: Human escalation queue and metrics
+        '401':
+          description: Unauthorized
+  /v1/escalations/{escalationId}/decision:
+    post:
+      operationId: decideHumanEscalation
+      security:
+        - bearerAuth: []
+          humanReviewerKey: []
+      parameters:
+        - in: path
+          name: escalationId
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/HumanEscalationDecision'
+      responses:
+        '200':
+          description: Human escalation decision recorded
+        '400':
+          description: Invalid decision or the authenticated reviewer matches the requester
+        '401':
+          description: Unauthorized
+        '403':
+          description: Missing or invalid human reviewer credential
+        '503':
+          description: Human reviewer identity is not configured