thumbgate 1.28.4 → 1.29.2

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]
@@ -338,6 +472,150 @@ components:
         sprintBriefUrl:
           type: string
           format: uri
+    WorkflowIntakeClosePacket:
+      type: object
+      required:
+        - status
+        - leadId
+        - blockers
+        - verificationPlan
+        - externalActionAuthorized
+        - revenueRecognized
+      properties:
+        status:
+          type: string
+          enum: [approval_ready_not_authorized, hold_not_approval_ready]
+        leadId:
+          type: string
+        destination:
+          type: object
+          nullable: true
+          properties:
+            channel:
+              type: string
+              enum: [email]
+            address:
+              type: string
+              format: email
+        offer:
+          type: object
+          nullable: true
+          additionalProperties: true
+        draft:
+          type: object
+          nullable: true
+          properties:
+            subject:
+              type: string
+            body:
+              type: string
+        approvalPhrase:
+          type: string
+          nullable: true
+        blockers:
+          type: array
+          items:
+            type: string
+        evidence:
+          type: object
+          additionalProperties: true
+        verificationPlan:
+          type: array
+          items:
+            type: string
+        externalActionAuthorized:
+          type: boolean
+          enum: [false]
+        revenueRecognized:
+          type: boolean
+          enum: [false]
+    WorkflowIntakeDiscoveryPacket:
+      type: object
+      required:
+        - type
+        - status
+        - leadId
+        - blockers
+        - verificationPlan
+        - externalActionAuthorized
+        - revenueRecognized
+      properties:
+        type:
+          type: string
+          enum: [discovery_questions]
+        status:
+          type: string
+          enum: [approval_ready_not_authorized, hold_not_approval_ready]
+        leadId:
+          type: string
+        destination:
+          type: object
+          nullable: true
+          properties:
+            channel:
+              type: string
+              enum: [email]
+            address:
+              type: string
+              format: email
+        draft:
+          type: object
+          nullable: true
+          properties:
+            subject:
+              type: string
+            body:
+              type: string
+        approvalPhrase:
+          type: string
+          nullable: true
+        blockers:
+          type: array
+          items:
+            type: string
+        evidence:
+          type: object
+          additionalProperties: true
+        verificationPlan:
+          type: array
+          items:
+            type: string
+        externalActionAuthorized:
+          type: boolean
+          enum: [false]
+        revenueRecognized:
+          type: boolean
+          enum: [false]
+    WorkflowIntakeQueueResponse:
+      type: object
+      required: [generatedAt, total, eligibleTotal, returned, approvalReadyTotal, discoveryReadyTotal, leads]
+      properties:
+        generatedAt:
+          type: string
+          format: date-time
+        total:
+          type: integer
+        eligibleTotal:
+          type: integer
+        returned:
+          type: integer
+        approvalReadyTotal:
+          type: integer
+        discoveryReadyTotal:
+          type: integer
+        primaryApprovalAction:
+          nullable: true
+          allOf:
+            - $ref: '#/components/schemas/WorkflowIntakeClosePacket'
+        primaryDiscoveryAction:
+          nullable: true
+          allOf:
+            - $ref: '#/components/schemas/WorkflowIntakeDiscoveryPacket'
+        leads:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
     WorkflowSprintAdvanceRequest:
       type: object
       required: [leadId, status]
@@ -361,6 +639,66 @@ components:
           type: array
           items:
             type: string
+        qualificationReview:
+          type: object
+          description: Required evidence-based buyer qualification review when advancing to qualified.
+          required:
+            - severityAndFrequency
+            - measurableImpact
+            - urgencyAndTrigger
+            - decisionAuthority
+            - budgetMechanism
+            - offerFit
+            - proofRequired
+            - nextStep
+            - evidenceReferences
+            - zeroSpendStatus
+          properties:
+            severityAndFrequency:
+              type: string
+            measurableImpact:
+              type: string
+            urgencyAndTrigger:
+              type: string
+            decisionAuthority:
+              type: string
+            budgetMechanism:
+              type: string
+            offerFit:
+              type: string
+            proofRequired:
+              type: string
+            nextStep:
+              type: string
+            evidenceReferences:
+              type: array
+              minItems: 1
+              items:
+                type: string
+            zeroSpendStatus:
+              type: string
+              enum: [proceed_zero_cost]
+            priceUnderstandingConfirmed:
+              type: boolean
+            workflowCount:
+              type: integer
+              minimum: 1
+            authorityConfirmed:
+              type: boolean
+            urgencyDays:
+              type: integer
+              minimum: 1
+            budgetCents:
+              type: integer
+              minimum: 0
+            readyToImplement:
+              type: boolean
+            proofBackedSprint:
+              type: boolean
+            completedEnterprisePilot:
+              type: boolean
+            requiresUnavailableHostedFeature:
+              type: boolean
     WorkflowSprintAdvanceResponse:
       type: object
       properties:
@@ -1104,6 +1442,36 @@ paths:
                 $ref: '#/components/schemas/WorkflowSprintIntakeResponse'
         '400':
           description: Invalid sprint intake request
+  /v1/intake/workflow-sprint/queue:
+    get:
+      operationId: getWorkflowSprintCloseQueue
+      parameters:
+        - in: query
+          name: status
+          description: Comma-separated workflow lifecycle statuses or all.
+          schema:
+            type: string
+            default: new,qualified
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 50
+      responses:
+        '200':
+          description: Private no-store intake queue with fail-closed approval packets
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WorkflowIntakeQueueResponse'
+        '400':
+          description: Invalid queue filter
+        '403':
+          description: Forbidden
+        '503':
+          description: Workflow intake capability is unavailable in this runtime
   /v1/intake/workflow-sprint/advance:
     post:
       operationId: advanceWorkflowSprintLead
@@ -1695,13 +2063,115 @@ paths:
           description: Webhook accepted
         '400':
           description: Invalid webhook signature or payload
-k signature or payload
-  /v1/billing/github-webhook:
+  /v1/billing/paypal-webhook:
     post:
-      operationId: githubMarketplaceWebhook
+      operationId: paypalBillingWebhook
       security: []
       responses:
         '200':
-          description: Webhook accepted
+          description: PayPal-verified payment event durably recorded
         '400':
-          description: Invalid webhook signature or payload
+          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