@vorionsys/platform-core 0.1.0

package/dist/friction/openapi.js

@@ -0,0 +1,883 @@
+/**
+ * OpenAPI 3.1 Specification for the Friction Feedback Module API
+ *
+ * This module exports a comprehensive OpenAPI specification for all friction
+ * feedback endpoints including feedback generation, signal recording, and
+ * pattern analysis.
+ *
+ * @packageDocumentation
+ */
+/**
+ * OpenAPI 3.1 specification for the Friction module
+ */
+export const frictionOpenApiSpec = {
+    openapi: '3.1.0',
+    info: {
+        title: 'Vorion Friction Feedback Module API',
+        version: '1.0.0',
+        description: `
+# Friction Feedback Module API
+
+The Friction Feedback module provides human-readable explanations and actionable
+guidance when agent actions are denied, escalated, or constrained. This improves
+the agent experience and enables learning from governance decisions.
+
+## Features
+
+- **Feedback Generation**: Generate human-readable explanations for governance decisions
+- **Understanding Signals**: Track how agents respond to friction feedback
+- **Pattern Analysis**: Analyze agent understanding patterns to improve communication
+- **Reviewer Decision Options**: Retrieve available options for human reviewers
+
+## Implements
+
+- FR119: Friction feedback generation
+- FR120: Understanding signal recording
+- FR121: Pattern analysis
+- FR122: Reviewer decision options
+
+## Authentication
+
+All endpoints require Bearer token authentication with a valid tenant context.
+
+## Rate Limiting
+
+API requests are rate-limited per tenant. Rate limit headers are included in responses.
+`,
+        contact: {
+            name: 'Vorion API Support',
+            email: 'api-support@vorion.io',
+        },
+        license: {
+            name: 'MIT',
+            url: 'https://opensource.org/licenses/MIT',
+        },
+    },
+    servers: [
+        {
+            url: '/api/v1/friction',
+            description: 'Friction API v1 base path',
+        },
+    ],
+    tags: [
+        {
+            name: 'Feedback',
+            description: 'Friction feedback generation',
+        },
+        {
+            name: 'Signals',
+            description: 'Agent understanding signal management',
+        },
+        {
+            name: 'Analysis',
+            description: 'Pattern analysis and insights',
+        },
+        {
+            name: 'Configuration',
+            description: 'Friction configuration and options',
+        },
+    ],
+    paths: {
+        '/feedback': {
+            post: {
+                tags: ['Feedback'],
+                summary: 'Generate friction feedback',
+                operationId: 'generateFeedback',
+                description: `
+Generate friction feedback for a denied, escalated, or constrained action.
+
+Returns:
+- Human-readable explanation of why the action was blocked
+- Actionable next steps the agent can take
+- Trust improvement suggestions
+- Constraint violation details
+`,
+                security: [{ bearerAuth: [] }],
+                requestBody: {
+                    required: true,
+                    content: {
+                        'application/json': {
+                            schema: { $ref: '#/components/schemas/GenerateFeedbackRequest' },
+                            examples: {
+                                denied: {
+                                    summary: 'Denied action feedback',
+                                    value: {
+                                        intentId: '550e8400-e29b-41d4-a716-446655440000',
+                                        agentId: '123e4567-e89b-12d3-a456-426614174000',
+                                        decision: {
+                                            intentId: 'intent-123',
+                                            action: 'deny',
+                                            constraintsEvaluated: [
+                                                {
+                                                    constraintId: 'max-transaction-amount',
+                                                    passed: false,
+                                                    action: 'deny',
+                                                    reason: 'Transaction amount exceeds limit',
+                                                },
+                                            ],
+                                            trustScore: 450,
+                                            trustLevel: 3,
+                                            decidedAt: '2024-01-15T10:30:00.000Z',
+                                        },
+                                        action: 'transfer_funds',
+                                        category: 'financial',
+                                        parameters: {
+                                            amount: 50000,
+                                            currency: 'USD',
+                                        },
+                                    },
+                                },
+                                escalated: {
+                                    summary: 'Escalated action feedback',
+                                    value: {
+                                        intentId: '550e8400-e29b-41d4-a716-446655440001',
+                                        agentId: '123e4567-e89b-12d3-a456-426614174000',
+                                        decision: {
+                                            intentId: 'intent-456',
+                                            action: 'escalate',
+                                            trustScore: 550,
+                                            trustLevel: 4,
+                                            decidedAt: '2024-01-15T10:35:00.000Z',
+                                        },
+                                        action: 'access_sensitive_data',
+                                        category: 'data-access',
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+                responses: {
+                    '200': {
+                        description: 'Friction feedback generated successfully',
+                        content: {
+                            'application/json': {
+                                schema: { $ref: '#/components/schemas/FrictionFeedback' },
+                                example: {
+                                    feedbackId: 'fb-550e8400-e29b-41d4-a716-446655440000',
+                                    intentId: '550e8400-e29b-41d4-a716-446655440000',
+                                    agentId: '123e4567-e89b-12d3-a456-426614174000',
+                                    action: 'transfer_funds',
+                                    decision: 'deny',
+                                    explanation: 'Your request to transfer $50,000 was denied because it exceeds your current transaction limit of $10,000.',
+                                    nextSteps: [
+                                        'Request a limit increase through the approval workflow',
+                                        'Split the transaction into smaller amounts',
+                                        'Contact your administrator for emergency approval',
+                                    ],
+                                    trustContext: {
+                                        currentScore: 450,
+                                        currentLevel: 3,
+                                        requiredLevel: 5,
+                                        improvementSuggestions: [
+                                            'Complete additional verification steps',
+                                            'Build transaction history with smaller amounts',
+                                        ],
+                                    },
+                                    constraints: [
+                                        {
+                                            constraintId: 'max-transaction-amount',
+                                            name: 'Maximum Transaction Amount',
+                                            violated: true,
+                                            details: 'Limit: $10,000, Requested: $50,000',
+                                        },
+                                    ],
+                                    generatedAt: '2024-01-15T10:30:05.000Z',
+                                },
+                            },
+                        },
+                    },
+                    '400': { $ref: '#/components/responses/ValidationError' },
+                    '401': { $ref: '#/components/responses/Unauthorized' },
+                    '500': { $ref: '#/components/responses/InternalError' },
+                },
+            },
+        },
+        '/signals': {
+            post: {
+                tags: ['Signals'],
+                summary: 'Record an understanding signal',
+                operationId: 'recordSignal',
+                description: `
+Record how an agent responded to friction feedback.
+
+Signal types:
+- \`acknowledged\`: Agent acknowledged the feedback
+- \`confused\`: Agent indicated confusion
+- \`retried_same\`: Agent retried the same action
+- \`retried_modified\`: Agent retried with modifications
+- \`escalated\`: Agent escalated to a human
+- \`abandoned\`: Agent abandoned the action
+`,
+                security: [{ bearerAuth: [] }],
+                requestBody: {
+                    required: true,
+                    content: {
+                        'application/json': {
+                            schema: { $ref: '#/components/schemas/RecordSignalRequest' },
+                            examples: {
+                                acknowledged: {
+                                    summary: 'Agent acknowledged feedback',
+                                    value: {
+                                        agentId: '123e4567-e89b-12d3-a456-426614174000',
+                                        feedbackId: 'fb-550e8400-e29b-41d4-a716-446655440000',
+                                        type: 'acknowledged',
+                                        responseTimeMs: 1500,
+                                    },
+                                },
+                                retriedModified: {
+                                    summary: 'Agent retried with modifications',
+                                    value: {
+                                        agentId: '123e4567-e89b-12d3-a456-426614174000',
+                                        feedbackId: 'fb-550e8400-e29b-41d4-a716-446655440000',
+                                        type: 'retried_modified',
+                                        responseTimeMs: 5000,
+                                        context: {
+                                            modification: 'reduced_amount',
+                                            newAmount: 5000,
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+                responses: {
+                    '201': {
+                        description: 'Signal recorded successfully',
+                        content: {
+                            'application/json': {
+                                schema: { $ref: '#/components/schemas/UnderstandingSignal' },
+                            },
+                        },
+                    },
+                    '400': { $ref: '#/components/responses/ValidationError' },
+                    '500': { $ref: '#/components/responses/InternalError' },
+                },
+            },
+        },
+        '/signals/{agentId}': {
+            get: {
+                tags: ['Signals'],
+                summary: 'Get understanding signals for an agent',
+                operationId: 'getSignals',
+                description: 'Retrieve all understanding signals recorded for a specific agent.',
+                security: [{ bearerAuth: [] }],
+                parameters: [
+                    {
+                        name: 'agentId',
+                        in: 'path',
+                        required: true,
+                        description: 'Agent UUID',
+                        schema: {
+                            type: 'string',
+                            format: 'uuid',
+                        },
+                    },
+                ],
+                responses: {
+                    '200': {
+                        description: 'List of understanding signals',
+                        content: {
+                            'application/json': {
+                                schema: { $ref: '#/components/schemas/SignalsListResponse' },
+                            },
+                        },
+                    },
+                    '400': { $ref: '#/components/responses/ValidationError' },
+                    '500': { $ref: '#/components/responses/InternalError' },
+                },
+            },
+        },
+        '/analysis/{agentId}': {
+            get: {
+                tags: ['Analysis'],
+                summary: 'Analyze understanding patterns',
+                operationId: 'analyzePatterns',
+                description: `
+Analyze understanding patterns for an agent.
+
+Returns:
+- Acknowledgment rate
+- Confusion rate
+- Retry patterns
+- Average response times
+- Recommendations for improving communication
+`,
+                security: [{ bearerAuth: [] }],
+                parameters: [
+                    {
+                        name: 'agentId',
+                        in: 'path',
+                        required: true,
+                        description: 'Agent UUID',
+                        schema: {
+                            type: 'string',
+                            format: 'uuid',
+                        },
+                    },
+                ],
+                responses: {
+                    '200': {
+                        description: 'Pattern analysis results',
+                        content: {
+                            'application/json': {
+                                schema: { $ref: '#/components/schemas/PatternAnalysisResponse' },
+                                example: {
+                                    agentId: '123e4567-e89b-12d3-a456-426614174000',
+                                    analysis: {
+                                        totalSignals: 50,
+                                        acknowledgmentRate: 0.72,
+                                        confusionRate: 0.08,
+                                        retryRate: 0.15,
+                                        abandonmentRate: 0.05,
+                                        avgResponseTimeMs: 2500,
+                                        patterns: {
+                                            mostCommonResponse: 'acknowledged',
+                                            improvementTrend: 'positive',
+                                        },
+                                        recommendations: [
+                                            'Agent shows good comprehension of feedback',
+                                            'Consider reducing friction for routine operations',
+                                        ],
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    '400': { $ref: '#/components/responses/ValidationError' },
+                    '500': { $ref: '#/components/responses/InternalError' },
+                },
+            },
+        },
+        '/decision-options': {
+            get: {
+                tags: ['Configuration'],
+                summary: 'Get reviewer decision options',
+                operationId: 'getDecisionOptions',
+                description: 'Retrieve available decision options for human reviewers when handling escalations.',
+                responses: {
+                    '200': {
+                        description: 'List of decision options',
+                        content: {
+                            'application/json': {
+                                schema: { $ref: '#/components/schemas/DecisionOptionsResponse' },
+                                example: {
+                                    options: [
+                                        {
+                                            value: 'approve',
+                                            label: 'Approve',
+                                            description: 'Allow the action to proceed',
+                                        },
+                                        {
+                                            value: 'approve_once',
+                                            label: 'Approve Once',
+                                            description: 'Allow this specific instance only',
+                                        },
+                                        {
+                                            value: 'deny',
+                                            label: 'Deny',
+                                            description: 'Block the action',
+                                        },
+                                        {
+                                            value: 'escalate_further',
+                                            label: 'Escalate Further',
+                                            description: 'Escalate to a higher authority',
+                                        },
+                                        {
+                                            value: 'request_modification',
+                                            label: 'Request Modification',
+                                            description: 'Ask the agent to modify the request',
+                                        },
+                                    ],
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+    components: {
+        securitySchemes: {
+            bearerAuth: {
+                type: 'http',
+                scheme: 'bearer',
+                bearerFormat: 'JWT',
+                description: 'JWT token with tenantId claim',
+            },
+        },
+        schemas: {
+            GenerateFeedbackRequest: {
+                type: 'object',
+                description: 'Request to generate friction feedback',
+                required: ['intentId', 'agentId', 'decision', 'action'],
+                properties: {
+                    intentId: {
+                        type: 'string',
+                        format: 'uuid',
+                        description: 'Intent UUID',
+                    },
+                    agentId: {
+                        type: 'string',
+                        format: 'uuid',
+                        description: 'Agent UUID',
+                    },
+                    decision: {
+                        $ref: '#/components/schemas/GovernanceDecision',
+                    },
+                    action: {
+                        type: 'string',
+                        description: 'The action that was attempted',
+                    },
+                    category: {
+                        type: 'string',
+                        description: 'Action category (e.g., financial, data-access)',
+                    },
+                    parameters: {
+                        type: 'object',
+                        additionalProperties: true,
+                        description: 'Action parameters',
+                    },
+                },
+            },
+            GovernanceDecision: {
+                type: 'object',
+                description: 'Governance decision details',
+                required: ['intentId', 'action', 'trustScore', 'trustLevel', 'decidedAt'],
+                properties: {
+                    intentId: {
+                        type: 'string',
+                        description: 'Intent identifier',
+                    },
+                    action: {
+                        type: 'string',
+                        enum: ['allow', 'deny', 'escalate', 'constrain'],
+                        description: 'Decision action',
+                    },
+                    constraintsEvaluated: {
+                        type: 'array',
+                        items: { $ref: '#/components/schemas/ConstraintEvaluation' },
+                        description: 'Constraints that were evaluated',
+                    },
+                    trustScore: {
+                        type: 'integer',
+                        minimum: 0,
+                        maximum: 1000,
+                        description: 'Trust score at decision time',
+                    },
+                    trustLevel: {
+                        type: 'integer',
+                        minimum: 0,
+                        maximum: 7,
+                        description: 'Trust level at decision time',
+                    },
+                    decidedAt: {
+                        type: 'string',
+                        format: 'date-time',
+                        description: 'Decision timestamp',
+                    },
+                },
+            },
+            ConstraintEvaluation: {
+                type: 'object',
+                description: 'Result of constraint evaluation',
+                required: ['constraintId', 'passed'],
+                properties: {
+                    constraintId: {
+                        type: 'string',
+                        description: 'Constraint identifier',
+                    },
+                    passed: {
+                        type: 'boolean',
+                        description: 'Whether the constraint passed',
+                    },
+                    action: {
+                        type: 'string',
+                        description: 'Action taken due to this constraint',
+                    },
+                    reason: {
+                        type: 'string',
+                        description: 'Human-readable reason',
+                    },
+                    details: {
+                        type: 'object',
+                        additionalProperties: true,
+                        description: 'Additional details',
+                    },
+                    durationMs: {
+                        type: 'number',
+                        description: 'Evaluation duration in milliseconds',
+                    },
+                    evaluatedAt: {
+                        type: 'string',
+                        format: 'date-time',
+                        description: 'Evaluation timestamp',
+                    },
+                },
+            },
+            FrictionFeedback: {
+                type: 'object',
+                description: 'Generated friction feedback',
+                required: ['feedbackId', 'intentId', 'agentId', 'action', 'decision', 'explanation', 'nextSteps', 'generatedAt'],
+                properties: {
+                    feedbackId: {
+                        type: 'string',
+                        description: 'Unique feedback identifier',
+                    },
+                    intentId: {
+                        type: 'string',
+                        format: 'uuid',
+                        description: 'Associated intent ID',
+                    },
+                    agentId: {
+                        type: 'string',
+                        format: 'uuid',
+                        description: 'Agent ID',
+                    },
+                    action: {
+                        type: 'string',
+                        description: 'The action that was attempted',
+                    },
+                    decision: {
+                        type: 'string',
+                        enum: ['deny', 'escalate', 'constrain'],
+                        description: 'Governance decision',
+                    },
+                    explanation: {
+                        type: 'string',
+                        description: 'Human-readable explanation',
+                    },
+                    nextSteps: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Actionable next steps',
+                    },
+                    trustContext: {
+                        $ref: '#/components/schemas/TrustContext',
+                    },
+                    constraints: {
+                        type: 'array',
+                        items: { $ref: '#/components/schemas/ConstraintFeedback' },
+                        description: 'Constraint-specific feedback',
+                    },
+                    generatedAt: {
+                        type: 'string',
+                        format: 'date-time',
+                        description: 'Generation timestamp',
+                    },
+                },
+            },
+            TrustContext: {
+                type: 'object',
+                description: 'Trust context for feedback',
+                properties: {
+                    currentScore: {
+                        type: 'integer',
+                        description: 'Current trust score',
+                    },
+                    currentLevel: {
+                        type: 'integer',
+                        description: 'Current trust level',
+                    },
+                    requiredLevel: {
+                        type: 'integer',
+                        description: 'Required trust level for the action',
+                    },
+                    improvementSuggestions: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Suggestions to improve trust',
+                    },
+                },
+            },
+            ConstraintFeedback: {
+                type: 'object',
+                description: 'Feedback for a specific constraint',
+                properties: {
+                    constraintId: {
+                        type: 'string',
+                        description: 'Constraint identifier',
+                    },
+                    name: {
+                        type: 'string',
+                        description: 'Human-readable constraint name',
+                    },
+                    violated: {
+                        type: 'boolean',
+                        description: 'Whether the constraint was violated',
+                    },
+                    details: {
+                        type: 'string',
+                        description: 'Violation details',
+                    },
+                },
+            },
+            RecordSignalRequest: {
+                type: 'object',
+                description: 'Request to record an understanding signal',
+                required: ['agentId', 'feedbackId', 'type', 'responseTimeMs'],
+                properties: {
+                    agentId: {
+                        type: 'string',
+                        format: 'uuid',
+                        description: 'Agent UUID',
+                    },
+                    feedbackId: {
+                        type: 'string',
+                        description: 'Feedback ID that this signal responds to',
+                    },
+                    type: {
+                        type: 'string',
+                        enum: ['acknowledged', 'confused', 'retried_same', 'retried_modified', 'escalated', 'abandoned'],
+                        description: 'Signal type',
+                    },
+                    responseTimeMs: {
+                        type: 'number',
+                        minimum: 0,
+                        description: 'Time to respond in milliseconds',
+                    },
+                    context: {
+                        type: 'object',
+                        additionalProperties: true,
+                        description: 'Additional context for the signal',
+                    },
+                },
+            },
+            UnderstandingSignal: {
+                type: 'object',
+                description: 'Recorded understanding signal',
+                required: ['signalId', 'agentId', 'feedbackId', 'type', 'responseTimeMs', 'recordedAt'],
+                properties: {
+                    signalId: {
+                        type: 'string',
+                        description: 'Unique signal identifier',
+                    },
+                    agentId: {
+                        type: 'string',
+                        format: 'uuid',
+                        description: 'Agent UUID',
+                    },
+                    feedbackId: {
+                        type: 'string',
+                        description: 'Associated feedback ID',
+                    },
+                    type: {
+                        type: 'string',
+                        enum: ['acknowledged', 'confused', 'retried_same', 'retried_modified', 'escalated', 'abandoned'],
+                        description: 'Signal type',
+                    },
+                    responseTimeMs: {
+                        type: 'number',
+                        description: 'Response time in milliseconds',
+                    },
+                    context: {
+                        type: 'object',
+                        additionalProperties: true,
+                        description: 'Signal context',
+                    },
+                    recordedAt: {
+                        type: 'string',
+                        format: 'date-time',
+                        description: 'Recording timestamp',
+                    },
+                },
+            },
+            SignalsListResponse: {
+                type: 'object',
+                description: 'List of understanding signals',
+                properties: {
+                    agentId: {
+                        type: 'string',
+                        format: 'uuid',
+                        description: 'Agent UUID',
+                    },
+                    signals: {
+                        type: 'array',
+                        items: { $ref: '#/components/schemas/UnderstandingSignal' },
+                    },
+                    count: {
+                        type: 'integer',
+                        description: 'Total number of signals',
+                    },
+                },
+            },
+            PatternAnalysisResponse: {
+                type: 'object',
+                description: 'Pattern analysis results',
+                properties: {
+                    agentId: {
+                        type: 'string',
+                        format: 'uuid',
+                        description: 'Agent UUID',
+                    },
+                    analysis: {
+                        type: 'object',
+                        properties: {
+                            totalSignals: {
+                                type: 'integer',
+                                description: 'Total signals analyzed',
+                            },
+                            acknowledgmentRate: {
+                                type: 'number',
+                                minimum: 0,
+                                maximum: 1,
+                                description: 'Rate of acknowledged signals',
+                            },
+                            confusionRate: {
+                                type: 'number',
+                                minimum: 0,
+                                maximum: 1,
+                                description: 'Rate of confused signals',
+                            },
+                            retryRate: {
+                                type: 'number',
+                                minimum: 0,
+                                maximum: 1,
+                                description: 'Rate of retry signals',
+                            },
+                            abandonmentRate: {
+                                type: 'number',
+                                minimum: 0,
+                                maximum: 1,
+                                description: 'Rate of abandoned signals',
+                            },
+                            avgResponseTimeMs: {
+                                type: 'number',
+                                description: 'Average response time',
+                            },
+                            patterns: {
+                                type: 'object',
+                                properties: {
+                                    mostCommonResponse: {
+                                        type: 'string',
+                                        description: 'Most common signal type',
+                                    },
+                                    improvementTrend: {
+                                        type: 'string',
+                                        enum: ['positive', 'neutral', 'negative'],
+                                        description: 'Trend direction',
+                                    },
+                                },
+                            },
+                            recommendations: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Recommendations for improvement',
+                            },
+                        },
+                    },
+                },
+            },
+            DecisionOptionsResponse: {
+                type: 'object',
+                description: 'Available reviewer decision options',
+                properties: {
+                    options: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                value: {
+                                    type: 'string',
+                                    description: 'Option value',
+                                },
+                                label: {
+                                    type: 'string',
+                                    description: 'Display label',
+                                },
+                                description: {
+                                    type: 'string',
+                                    description: 'Option description',
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            Error: {
+                type: 'object',
+                description: 'Error response',
+                properties: {
+                    error: {
+                        type: 'string',
+                        description: 'Error type',
+                    },
+                    message: {
+                        type: 'string',
+                        description: 'Error message',
+                    },
+                    details: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            additionalProperties: true,
+                        },
+                        description: 'Validation error details',
+                    },
+                },
+            },
+        },
+        responses: {
+            ValidationError: {
+                description: 'Validation error - invalid request body',
+                content: {
+                    'application/json': {
+                        schema: { $ref: '#/components/schemas/Error' },
+                        example: {
+                            error: 'Validation Error',
+                            message: 'Invalid request body',
+                            details: [
+                                {
+                                    code: 'invalid_type',
+                                    path: ['agentId'],
+                                    message: 'Expected string, received undefined',
+                                },
+                            ],
+                        },
+                    },
+                },
+            },
+            Unauthorized: {
+                description: 'Unauthorized - missing or invalid authentication',
+                content: {
+                    'application/json': {
+                        schema: { $ref: '#/components/schemas/Error' },
+                        example: {
+                            error: 'Unauthorized',
+                            message: 'Tenant ID required',
+                        },
+                    },
+                },
+            },
+            InternalError: {
+                description: 'Internal server error',
+                content: {
+                    'application/json': {
+                        schema: { $ref: '#/components/schemas/Error' },
+                        example: {
+                            error: 'Internal Server Error',
+                            message: 'Failed to generate friction feedback',
+                        },
+                    },
+                },
+            },
+        },
+    },
+    security: [
+        { bearerAuth: [] },
+    ],
+};
+/**
+ * Get the OpenAPI specification as a JSON string
+ */
+export function getFrictionOpenApiSpecJson() {
+    return JSON.stringify(frictionOpenApiSpec, null, 2);
+}
+/**
+ * Get the OpenAPI specification object
+ */
+export function getFrictionOpenApiSpec() {
+    return frictionOpenApiSpec;
+}
+//# sourceMappingURL=openapi.js.map