@sequenceholdings/agent-spec 0.1.1 → 0.1.3

package/dist/voice-runs-evidence.js

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+import { voiceIdSchema, voiceTimestampSchema } from './voice-common.js';
+import { sameVoiceResource, voiceResourceReferenceSchema } from './voice-authority-contracts.js';
+export const voiceRunSanitizedTextSchema = z.string().trim().min(1).max(2_000);
+const MAX_JSON_BYTES = 16 * 1024;
+const SECRET_KEY = /(?:^|[_-])(authorization|credential|password|secret|token|api[_-]?key|call[_-]?grant)(?:$|[_-])/i;
+function findSecretKey({ value, path }) {
+    if (Array.isArray(value)) {
+        for (const [index, entry] of value.entries()) {
+            const found = findSecretKey({ value: entry, path: `${path}[${index}]` });
+            if (found !== null)
+                return found;
+        }
+        return null;
+    }
+    if (value === null || typeof value !== 'object')
+        return null;
+    for (const [key, entry] of Object.entries(value)) {
+        if (SECRET_KEY.test(key))
+            return `${path}.${key}`;
+        const found = findSecretKey({ value: entry, path: `${path}.${key}` });
+        if (found !== null)
+            return found;
+    }
+    return null;
+}
+function boundedEvidenceValue(maxBytes) {
+    return z.json().superRefine((value, context) => {
+        if (Buffer.byteLength(JSON.stringify(value), 'utf8') > maxBytes) {
+            context.addIssue({ code: 'custom', message: `run evidence exceeds ${maxBytes} bytes` });
+        }
+        const secretPath = findSecretKey({ value, path: '(root)' });
+        if (secretPath !== null) {
+            context.addIssue({
+                code: 'custom', message: `${secretPath} is a secret-bearing key and cannot be retained`,
+            });
+        }
+    });
+}
+export const voiceBoundedRunEvidenceValueSchema = boundedEvidenceValue(MAX_JSON_BYTES);
+export const voiceDetailedRunEvidenceValueSchema = boundedEvidenceValue(64 * 1024);
+export const voiceTranscriptEntrySchema = z.strictObject({
+    sequence: z.number().int().nonnegative().safe(),
+    speaker: z.enum(['AGENT', 'CALLER', 'TOOL', 'SYSTEM']),
+    text: z.string().max(8_000),
+    startedAt: voiceTimestampSchema.nullable(),
+    endedAt: voiceTimestampSchema.nullable(),
+});
+const availableTranscript = z.strictObject({
+    status: z.literal('AVAILABLE'), transcriptReferenceId: voiceIdSchema,
+    capturedAt: voiceTimestampSchema, entries: z.array(voiceTranscriptEntrySchema).min(1).max(500),
+    sanitizedDetail: z.null(),
+});
+const absentTranscript = z.strictObject({
+    status: z.enum(['PENDING', 'MISSING']), transcriptReferenceId: z.null(),
+    capturedAt: voiceTimestampSchema.nullable(), entries: z.array(voiceTranscriptEntrySchema).length(0),
+    sanitizedDetail: voiceRunSanitizedTextSchema,
+});
+const contradictoryTranscript = z.strictObject({
+    status: z.literal('CONTRADICTORY'), transcriptReferenceId: voiceIdSchema.nullable(),
+    capturedAt: voiceTimestampSchema.nullable(), entries: z.array(voiceTranscriptEntrySchema).max(500),
+    sanitizedDetail: voiceRunSanitizedTextSchema,
+});
+export const voiceTranscriptSchema = z.discriminatedUnion('status', [
+    availableTranscript, absentTranscript, contradictoryTranscript,
+]).superRefine((value, context) => {
+    if (value.entries.reduce((total, { text }) => total + text.length, 0) > 250_000) {
+        context.addIssue({ code: 'custom', path: ['entries'], message: 'transcript text is too large' });
+    }
+    const sequences = value.entries.map(({ sequence }) => sequence);
+    if (new Set(sequences).size !== sequences.length) {
+        context.addIssue({ code: 'custom', path: ['entries'], message: 'sequences must be unique' });
+    }
+});
+export const voiceCompletionEventKindSchema = z.literal('CALL_COMPLETED');
+export const voiceLogicalCompletionEventIdentitySchema = z.strictObject({
+    sessionId: voiceIdSchema, kind: voiceCompletionEventKindSchema,
+});
+export function voiceLogicalCompletionEventKey({ sessionId, kind }) {
+    const identity = voiceLogicalCompletionEventIdentitySchema.parse({ sessionId, kind });
+    return JSON.stringify([identity.sessionId, identity.kind]);
+}
+export const voiceCompletionEventSchema = z.strictObject({
+    eventId: voiceIdSchema,
+    logicalIdentity: voiceLogicalCompletionEventIdentitySchema,
+    providerDeliveryIds: z.array(voiceIdSchema).max(100)
+        .refine((values) => new Set(values).size === values.length, {
+        message: 'provider delivery IDs must be unique evidence references',
+    }),
+    evidenceStatus: z.enum(['CONFIRMED', 'PENDING', 'CONTRADICTORY']),
+    persistedAt: voiceTimestampSchema,
+    providerConversationId: voiceIdSchema.nullable(),
+});
+export const voiceTelephoneOutcomeSchema = z.enum(['COMPLETED', 'FAILED', 'CANCELLED', 'UNKNOWN']);
+export const voiceBusinessOutcomeSchema = z.enum([
+    'SUCCEEDED', 'FAILED', 'PARTIAL', 'NOT_REQUESTED', 'UNKNOWN',
+]);
+export const voiceRunWritebackStatusSchema = z.enum([
+    'PENDING', 'COMPLETE', 'FAILED', 'RECONCILIATION_REQUIRED',
+]);
+export const voiceRunEvidenceStatusSchema = z.enum([
+    'COMPLETE', 'PENDING', 'INCOMPLETE', 'CONTRADICTORY',
+]);
+export const voiceSyntheticResourceEvidenceSchema = z.strictObject({
+    candidate: z.strictObject({
+        fixtureId: voiceIdSchema, syntheticResource: voiceResourceReferenceSchema,
+    }).nullable(),
+    verifiedResource: voiceResourceReferenceSchema.nullable(),
+    verificationStatus: z.enum([
+        'NOT_VERIFIED', 'VERIFIED', 'FAILED', 'LOCKED', 'EXPIRED', 'REVOKED', 'UNKNOWN',
+    ]),
+}).superRefine((value, context) => {
+    if (value.verificationStatus === 'VERIFIED') {
+        if (value.candidate === null || value.verifiedResource === null ||
+            !sameVoiceResource({ left: value.candidate.syntheticResource, right: value.verifiedResource })) {
+            context.addIssue({ code: 'custom', message: 'verified resource must match candidate' });
+        }
+    }
+    else if (value.verifiedResource !== null) {
+        context.addIssue({ code: 'custom', message: 'unverified evidence cannot claim a resource' });
+    }
+});
+export const voiceRunEvidenceRetentionSchema = z.strictObject({
+    policy: z.literal('UNLIMITED'),
+    ageBasedExpiry: z.literal(false),
+    appliesTo: z.tuple([
+        z.literal('TRANSCRIPT'), z.literal('TOOL_EVIDENCE'), z.literal('COMPLETION_EVENT'),
+        z.literal('RUN_METADATA'), z.literal('RECORDING'),
+    ]),
+});
+const providerUnlimitedRetention = z.strictObject({
+    policy: z.literal('UNLIMITED'), providerRetentionDays: z.literal(-1),
+    evidenceRef: z.string().trim().min(1).max(500),
+});
+export const voiceRunRecordingSchema = z.discriminatedUnion('status', [
+    z.strictObject({
+        status: z.literal('DISABLED'), enabled: z.literal(false), providerRetention: z.null(),
+        sanitizedDetail: voiceRunSanitizedTextSchema,
+    }),
+    z.strictObject({
+        status: z.literal('PENDING'), enabled: z.literal(true),
+        providerRetention: providerUnlimitedRetention,
+        sanitizedDetail: voiceRunSanitizedTextSchema.nullable(),
+    }),
+    z.strictObject({
+        status: z.literal('AVAILABLE'), enabled: z.literal(true),
+        providerRetention: providerUnlimitedRetention, sanitizedDetail: z.null(),
+    }),
+    z.strictObject({
+        status: z.literal('UNAVAILABLE'), enabled: z.literal(true),
+        providerRetention: providerUnlimitedRetention,
+        sanitizedDetail: voiceRunSanitizedTextSchema,
+    }),
+]);