@sequenceholdings/agent-spec 0.1.1 → 0.1.3

package/dist/voice-api.js

@@ -0,0 +1,164 @@
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.js';
+import { voiceAgentDefinitionSchema } from './agent-definition.js';
+import { isReservedVoiceVariable, voiceAgentScopeSchema, voiceHashSchema, voiceIdSchema, voiceRevisionSchema, voiceScopeSchema, voiceTimestampSchema } from './voice-common.js';
+import { voiceDraftSchema, voiceSkillSourceStatusSchema } from './voice-drafts.js';
+import { voicePublicationOperationSchema, voiceSessionStateSchema } from './voice-lifecycle.js';
+import { voiceCompletionEventSchema, voiceCompletedRunDetailSchema, voiceRunWritebackStatusSchema } from './voice-runs.js';
+import { voiceCallLimitsSchema } from './voice-policy.js';
+import { voiceToolBindingSchema, voiceToolOperationRequirementSchema } from './voice-authority.js';
+const toolReviewConfirmationSchema = z.strictObject({ toolAlias: voiceIdSchema, bindingHash: voiceHashSchema });
+export const voiceErrorCodeSchema = z.enum([
+    'DENIED', 'DISABLED', 'STALE_REVISION', 'IDEMPOTENCY_CONFLICT', 'INVALID_DEFINITION',
+    'MODE_MISMATCH', 'INVALID_BINDING', 'SOURCE_MISSING', 'SOURCE_FORBIDDEN',
+    'LIMIT_REACHED', 'WAITING_FOR_IDLE', 'DEPENDENCY_MAINTENANCE', 'PROVIDER_FAILURE',
+    'UNCERTAIN_OPERATION', 'NOT_FOUND', 'INCOMPLETE_EVIDENCE',
+]);
+export const voiceErrorSchema = z.strictObject({
+    code: voiceErrorCodeSchema,
+    message: z.string().min(1).max(500),
+    correlationId: voiceIdSchema,
+});
+export const voicePublishRequestSchema = z.strictObject({
+    agentId: voiceIdSchema,
+    expectedDraftRevision: voiceRevisionSchema,
+    expectedDeploymentRevision: voiceRevisionSchema.nullable(),
+    idempotencyKey: voiceIdSchema,
+    toolReviewConfirmations: z.array(toolReviewConfirmationSchema).max(64).default([])
+        .refine((confirmations) => new Set(confirmations.map((item) => item.toolAlias)).size === confirmations.length, 'Duplicate tool review confirmation'),
+});
+export const voicePublicationReadRequestSchema = z.strictObject({ agentId: voiceIdSchema, operationId: voiceIdSchema });
+export const voicePublicationResponseSchema = z.strictObject({
+    operation: voicePublicationOperationSchema,
+    activeReleaseId: voiceIdSchema.nullable(),
+    deploymentRevision: voiceRevisionSchema,
+    desiredEnabled: z.boolean(),
+    publicationPaused: z.boolean(),
+    maintenancePaused: z.boolean(),
+    sources: z.array(voiceSkillSourceStatusSchema).max(32),
+});
+export const voicePublishValidationRequestSchema = z.strictObject({ agentId: voiceIdSchema, expectedDraftRevision: voiceRevisionSchema });
+export const voicePublishValidationResponseSchema = z.strictObject({
+    agentId: voiceIdSchema,
+    draftRevision: voiceRevisionSchema,
+    deploymentRevision: voiceRevisionSchema,
+    activeReleaseId: voiceIdSchema.nullable(),
+    authoredDefinitionHash: voiceHashSchema,
+    localProjectionHash: voiceHashSchema,
+    sources: z.array(voiceSkillSourceStatusSchema).max(32),
+    tools: z.array(z.strictObject({ binding: voiceToolBindingSchema, requirement: voiceToolOperationRequirementSchema,
+        bindingHash: voiceHashSchema, requiresConfirmation: z.boolean() })
+        .refine((tool) => tool.bindingHash === hashVoiceToolReviewBinding(tool), 'Tool review hash must include binding and operation policy')).max(64),
+});
+export function hashVoiceToolReviewBinding({ binding, requirement }) {
+    return createHash('sha256').update('sequence-voice-tool-review-v1\0')
+        .update(canonicalJson({ binding: voiceToolBindingSchema.parse(binding),
+        requirement: voiceToolOperationRequirementSchema.parse(requirement) })).digest('hex');
+}
+export const voiceOutboundCallRequestSchema = z.strictObject({
+    agentId: voiceIdSchema,
+    expectedActiveReleaseId: voiceIdSchema,
+    destinationId: voiceIdSchema,
+    fixtureId: voiceIdSchema,
+    idempotencyKey: voiceIdSchema,
+});
+export function hashVoiceOutboundRequest({ context, request }) {
+    const scope = voiceScopeSchema.parse(context.scope);
+    const actorPrincipalId = voiceIdSchema.parse(context.actorPrincipalId);
+    return createHash('sha256').update('sequence-voice-outbound-request-v1\0')
+        .update(canonicalJson({ scope, actorPrincipalId, request: voiceOutboundCallRequestSchema.parse(request) })).digest('hex');
+}
+export const voiceSettingsUpdateRequestSchema = z.strictObject({
+    expectedRevision: voiceRevisionSchema,
+    limits: voiceCallLimitsSchema.extend({
+        maxDailyInboundAttemptsPerNumber: voiceCallLimitsSchema.shape.maxDailyInboundAttemptsPerNumber.unwrap(),
+        maxConcurrentInboundCallsPerNumber: voiceCallLimitsSchema.shape.maxConcurrentInboundCallsPerNumber.unwrap(),
+    }),
+});
+export const voiceViewerUsageSchema = z.strictObject({
+    policyRevision: voiceRevisionSchema,
+    limits: voiceCallLimitsSchema,
+    utcDay: z.iso.date(),
+    resetsAt: voiceTimestampSchema,
+    activeReservations: z.number().int().nonnegative().safe(),
+    admittedAttempts: z.number().int().nonnegative().safe(),
+    personalOutboundAttempts: z.number().int().nonnegative().safe(),
+});
+export const voiceInboundAdmissionEvidenceSchema = voiceAgentScopeSchema.extend({
+    twilioAccountSid: voiceIdSchema,
+    twilioCallSid: voiceIdSchema,
+    ownedNumberId: voiceIdSchema,
+    routeId: voiceIdSchema,
+    routeRevision: voiceRevisionSchema,
+    checkedAt: voiceTimestampSchema,
+    currentPreAnswerIdentityVerified: z.literal(true),
+});
+export const voiceCallResponseSchema = z.strictObject({
+    sessionId: voiceIdSchema,
+    agentId: voiceIdSchema,
+    releaseId: voiceIdSchema,
+    revision: voiceRevisionSchema,
+    state: voiceSessionStateSchema,
+});
+export const voiceDispatchCallCommandSchema = voiceScopeSchema.extend({
+    sessionId: voiceIdSchema,
+    expectedRevision: voiceRevisionSchema,
+    operationId: voiceIdSchema,
+});
+export const voiceToolDispatchRequestSchema = z.strictObject({
+    toolAlias: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/),
+    providerDeliveryId: voiceIdSchema,
+    arguments: z.record(z.string().min(1).max(64), z.json()),
+}).superRefine((request, context) => {
+    for (const key of Object.keys(request.arguments))
+        if (isReservedVoiceVariable({ name: key })) {
+            context.addIssue({ code: 'custom', path: ['arguments', key], message: 'Reserved runtime authority field' });
+        }
+    if (JSON.stringify(request.arguments).length > 64_000) {
+        context.addIssue({ code: 'custom', path: ['arguments'], message: 'Tool arguments exceed the contract size bound' });
+    }
+});
+export const voiceCompletionCommandSchema = voiceScopeSchema.extend({
+    sessionId: voiceIdSchema,
+    deliveryReceiptId: voiceIdSchema,
+    deliveryBodyHash: voiceHashSchema,
+    event: voiceCompletionEventSchema,
+}).refine((command) => command.event.logicalIdentity.sessionId === command.sessionId, { path: ['event', 'logicalIdentity', 'sessionId'], message: 'Completion must refer to the known session' });
+export const voiceCompletionResponseSchema = z.strictObject({
+    sessionId: voiceIdSchema,
+    runId: voiceIdSchema,
+    completionEventId: voiceIdSchema,
+    duplicate: z.boolean(),
+    writebackStatus: voiceRunWritebackStatusSchema,
+});
+export const voiceAgentControlRequestSchema = z.strictObject({
+    agentId: voiceIdSchema,
+    expectedRevision: voiceRevisionSchema,
+    action: z.enum(['ENABLE', 'CLOSE_ADMISSION', 'KILL']),
+    idempotencyKey: voiceIdSchema,
+});
+export const voiceAgentDisableRequestSchema = voiceAgentControlRequestSchema.pick({ agentId: true, expectedRevision: true });
+export const voiceAgentDisableResponseSchema = z.strictObject({
+    agentId: voiceIdSchema, revision: voiceRevisionSchema, desiredEnabled: z.literal(false),
+    activeReleaseId: voiceIdSchema.nullable(), publicationPaused: z.boolean(), maintenancePaused: z.boolean(),
+});
+export const voiceEnvironmentControlRequestSchema = z.strictObject({
+    expectedRevision: voiceRevisionSchema,
+    action: z.enum(['ENABLE', 'CLOSE_ADMISSION', 'KILL']),
+    idempotencyKey: voiceIdSchema,
+});
+export const voiceCallCancelRequestSchema = z.strictObject({
+    sessionId: voiceIdSchema, expectedRevision: voiceRevisionSchema, idempotencyKey: voiceIdSchema,
+});
+export const voiceInboundRouteUpdateRequestSchema = z.strictObject({
+    ownedNumberId: voiceIdSchema, agentId: voiceIdSchema,
+    expectedRevision: voiceRevisionSchema.nullable(), enabled: z.boolean(),
+});
+export const voiceDependencyMaintenanceRequestSchema = z.strictObject({
+    managedFunctionId: voiceIdSchema, expectedRevision: voiceRevisionSchema.nullable(),
+    action: z.enum(['BEGIN', 'END']), idempotencyKey: voiceIdSchema,
+});
+export const voiceDraftReadResponseSchema = voiceDraftSchema;
+export const voiceDefinitionExportResponseSchema = voiceAgentDefinitionSchema;
+export const voiceRunReadResponseSchema = voiceCompletedRunDetailSchema;

package/dist/voice-authoring.d.ts

@@ -0,0 +1,463 @@
+import { z } from 'zod';
+export declare function hashVoiceSkillContent({ name, instructions }: {
+    name: string;
+    instructions: string;
+}): string;
+export declare const capturedVoiceProcedureSchema: z.ZodPipe<z.ZodObject<{
+    key: z.ZodString;
+    name: z.ZodString;
+    instructions: z.ZodString;
+    activationDescription: z.ZodString;
+    source: z.ZodObject<{
+        skillId: z.ZodString;
+        contentHash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    toolAliases: z.ZodDefault<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string[], string[]>>>;
+    subprocedures: z.ZodDefault<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string[], string[]>>>;
+}, z.core.$strict>, z.ZodTransform<{
+    source: {
+        skillId: string;
+        contentHash: string;
+    };
+    key: string;
+    name: string;
+    instructions: string;
+    activationDescription: string;
+    toolAliases: string[];
+    subprocedures: string[];
+}, {
+    key: string;
+    name: string;
+    instructions: string;
+    activationDescription: string;
+    source: {
+        skillId: string;
+        contentHash?: string | undefined;
+    };
+    toolAliases: string[];
+    subprocedures: string[];
+}>>;
+export type CapturedVoiceProcedure = z.infer<typeof capturedVoiceProcedureSchema>;
+export declare const voiceAuthoredToolSchema: z.ZodPipe<z.ZodObject<{
+    alias: z.ZodString;
+    description: z.ZodString;
+    managedFunction: z.ZodObject<{
+        ref: z.ZodString;
+        operation: z.ZodString;
+    }, z.core.$strict>;
+    inputMappings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        argument: z.ZodString;
+        parameter: z.ZodString;
+    }, z.core.$strict>>>;
+    outputMappings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        result: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>, z.ZodTransform<{
+    inputMappings: {
+        argument: string;
+        parameter: string;
+    }[];
+    outputMappings: {
+        field: string;
+        result: string;
+    }[];
+    alias: string;
+    description: string;
+    managedFunction: {
+        ref: string;
+        operation: string;
+    };
+}, {
+    alias: string;
+    description: string;
+    managedFunction: {
+        ref: string;
+        operation: string;
+    };
+    inputMappings: {
+        argument: string;
+        parameter: string;
+    }[];
+    outputMappings: {
+        field: string;
+        result: string;
+    }[];
+}>>;
+export type VoiceAuthoredTool = z.infer<typeof voiceAuthoredToolSchema>;
+export declare const voiceDeclarationSchema: z.ZodPipe<z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"1">;
+    voice: z.ZodString;
+    language: z.ZodString;
+    firstMessage: z.ZodString;
+    procedures: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodObject<{
+        key: z.ZodString;
+        name: z.ZodString;
+        instructions: z.ZodString;
+        activationDescription: z.ZodString;
+        source: z.ZodObject<{
+            skillId: z.ZodString;
+            contentHash: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        toolAliases: z.ZodDefault<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string[], string[]>>>;
+        subprocedures: z.ZodDefault<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string[], string[]>>>;
+    }, z.core.$strict>, z.ZodTransform<{
+        source: {
+            skillId: string;
+            contentHash: string;
+        };
+        key: string;
+        name: string;
+        instructions: string;
+        activationDescription: string;
+        toolAliases: string[];
+        subprocedures: string[];
+    }, {
+        key: string;
+        name: string;
+        instructions: string;
+        activationDescription: string;
+        source: {
+            skillId: string;
+            contentHash?: string | undefined;
+        };
+        toolAliases: string[];
+        subprocedures: string[];
+    }>>>>;
+    tools: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodObject<{
+        alias: z.ZodString;
+        description: z.ZodString;
+        managedFunction: z.ZodObject<{
+            ref: z.ZodString;
+            operation: z.ZodString;
+        }, z.core.$strict>;
+        inputMappings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            argument: z.ZodString;
+            parameter: z.ZodString;
+        }, z.core.$strict>>>;
+        outputMappings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            result: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>, z.ZodTransform<{
+        inputMappings: {
+            argument: string;
+            parameter: string;
+        }[];
+        outputMappings: {
+            field: string;
+            result: string;
+        }[];
+        alias: string;
+        description: string;
+        managedFunction: {
+            ref: string;
+            operation: string;
+        };
+    }, {
+        alias: string;
+        description: string;
+        managedFunction: {
+            ref: string;
+            operation: string;
+        };
+        inputMappings: {
+            argument: string;
+            parameter: string;
+        }[];
+        outputMappings: {
+            field: string;
+            result: string;
+        }[];
+    }>>>>;
+}, z.core.$strict>, z.ZodTransform<{
+    procedures: {
+        source: {
+            skillId: string;
+            contentHash: string;
+        };
+        key: string;
+        name: string;
+        instructions: string;
+        activationDescription: string;
+        toolAliases: string[];
+        subprocedures: string[];
+    }[];
+    tools: {
+        inputMappings: {
+            argument: string;
+            parameter: string;
+        }[];
+        outputMappings: {
+            field: string;
+            result: string;
+        }[];
+        alias: string;
+        description: string;
+        managedFunction: {
+            ref: string;
+            operation: string;
+        };
+    }[];
+    schemaVersion: "1";
+    voice: string;
+    language: string;
+    firstMessage: string;
+}, {
+    schemaVersion: "1";
+    voice: string;
+    language: string;
+    firstMessage: string;
+    procedures: {
+        source: {
+            skillId: string;
+            contentHash: string;
+        };
+        key: string;
+        name: string;
+        instructions: string;
+        activationDescription: string;
+        toolAliases: string[];
+        subprocedures: string[];
+    }[];
+    tools: {
+        inputMappings: {
+            argument: string;
+            parameter: string;
+        }[];
+        outputMappings: {
+            field: string;
+            result: string;
+        }[];
+        alias: string;
+        description: string;
+        managedFunction: {
+            ref: string;
+            operation: string;
+        };
+    }[];
+}>>;
+export type VoiceDeclaration = z.infer<typeof voiceDeclarationSchema>;
+export type VoiceDeclarationInput = z.input<typeof voiceDeclarationSchema>;
+export declare const voiceSupportedAuthoringOptionsSchema: z.ZodObject<{
+    voices: z.ZodArray<z.ZodString>;
+    languages: z.ZodArray<z.ZodString>;
+    models: z.ZodArray<z.ZodObject<{
+        provider: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type VoiceSupportedAuthoringOptions = z.infer<typeof voiceSupportedAuthoringOptionsSchema>;
+export declare function validateVoiceAuthoringOptions({ voice, model, supported }: {
+    voice: VoiceDeclaration;
+    model: {
+        provider: string;
+        name: string;
+    };
+    supported: VoiceSupportedAuthoringOptions;
+}): void;
+export declare const VOICE_LOCAL_PROJECTION_VERSION = "voice-free-form-v1";
+export declare const voiceProjectionInputSchema: z.ZodObject<{
+    systemPrompt: z.ZodString;
+    model: z.ZodObject<{
+        provider: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>;
+    voice: z.ZodPipe<z.ZodObject<{
+        schemaVersion: z.ZodLiteral<"1">;
+        voice: z.ZodString;
+        language: z.ZodString;
+        firstMessage: z.ZodString;
+        procedures: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodObject<{
+            key: z.ZodString;
+            name: z.ZodString;
+            instructions: z.ZodString;
+            activationDescription: z.ZodString;
+            source: z.ZodObject<{
+                skillId: z.ZodString;
+                contentHash: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            toolAliases: z.ZodDefault<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string[], string[]>>>;
+            subprocedures: z.ZodDefault<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string[], string[]>>>;
+        }, z.core.$strict>, z.ZodTransform<{
+            source: {
+                skillId: string;
+                contentHash: string;
+            };
+            key: string;
+            name: string;
+            instructions: string;
+            activationDescription: string;
+            toolAliases: string[];
+            subprocedures: string[];
+        }, {
+            key: string;
+            name: string;
+            instructions: string;
+            activationDescription: string;
+            source: {
+                skillId: string;
+                contentHash?: string | undefined;
+            };
+            toolAliases: string[];
+            subprocedures: string[];
+        }>>>>;
+        tools: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodObject<{
+            alias: z.ZodString;
+            description: z.ZodString;
+            managedFunction: z.ZodObject<{
+                ref: z.ZodString;
+                operation: z.ZodString;
+            }, z.core.$strict>;
+            inputMappings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                argument: z.ZodString;
+                parameter: z.ZodString;
+            }, z.core.$strict>>>;
+            outputMappings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                field: z.ZodString;
+                result: z.ZodString;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>, z.ZodTransform<{
+            inputMappings: {
+                argument: string;
+                parameter: string;
+            }[];
+            outputMappings: {
+                field: string;
+                result: string;
+            }[];
+            alias: string;
+            description: string;
+            managedFunction: {
+                ref: string;
+                operation: string;
+            };
+        }, {
+            alias: string;
+            description: string;
+            managedFunction: {
+                ref: string;
+                operation: string;
+            };
+            inputMappings: {
+                argument: string;
+                parameter: string;
+            }[];
+            outputMappings: {
+                field: string;
+                result: string;
+            }[];
+        }>>>>;
+    }, z.core.$strict>, z.ZodTransform<{
+        procedures: {
+            source: {
+                skillId: string;
+                contentHash: string;
+            };
+            key: string;
+            name: string;
+            instructions: string;
+            activationDescription: string;
+            toolAliases: string[];
+            subprocedures: string[];
+        }[];
+        tools: {
+            inputMappings: {
+                argument: string;
+                parameter: string;
+            }[];
+            outputMappings: {
+                field: string;
+                result: string;
+            }[];
+            alias: string;
+            description: string;
+            managedFunction: {
+                ref: string;
+                operation: string;
+            };
+        }[];
+        schemaVersion: "1";
+        voice: string;
+        language: string;
+        firstMessage: string;
+    }, {
+        schemaVersion: "1";
+        voice: string;
+        language: string;
+        firstMessage: string;
+        procedures: {
+            source: {
+                skillId: string;
+                contentHash: string;
+            };
+            key: string;
+            name: string;
+            instructions: string;
+            activationDescription: string;
+            toolAliases: string[];
+            subprocedures: string[];
+        }[];
+        tools: {
+            inputMappings: {
+                argument: string;
+                parameter: string;
+            }[];
+            outputMappings: {
+                field: string;
+                result: string;
+            }[];
+            alias: string;
+            description: string;
+            managedFunction: {
+                ref: string;
+                operation: string;
+            };
+        }[];
+    }>>;
+}, z.core.$strict>;
+export type VoiceProjectionInput = z.infer<typeof voiceProjectionInputSchema>;
+export declare function projectVoiceAuthoring(input: VoiceProjectionInput): {
+    digest: string;
+    systemPrompt: string;
+    model: {
+        provider: string;
+        name: string;
+    };
+    voice: {
+        procedures: {
+            source: {
+                skillId: string;
+                contentHash: string;
+            };
+            key: string;
+            name: string;
+            instructions: string;
+            activationDescription: string;
+            toolAliases: string[];
+            subprocedures: string[];
+        }[];
+        tools: {
+            inputMappings: {
+                argument: string;
+                parameter: string;
+            }[];
+            outputMappings: {
+                field: string;
+                result: string;
+            }[];
+            alias: string;
+            description: string;
+            managedFunction: {
+                ref: string;
+                operation: string;
+            };
+        }[];
+        schemaVersion: "1";
+        voice: string;
+        language: string;
+        firstMessage: string;
+    };
+    compilerVersion: string;
+};
+export type VoiceLocalProjection = ReturnType<typeof projectVoiceAuthoring>;